Witam, bawię się trochę doxygenem i mam pytanko - gdzie lepiej trzymać komentarze do funkcji - w plikach h czy c/cpp? Chodzi mi o ta warstwe opisu funkcji, parametrów itp.
Np Eclipse/Atollic itp po najechaniu kursorem na funkcję wyświetla nam jej zawartość z pliku .c łacznie z górnym komentarzem - czy iść w tym kierunku? Z drugiej strony głupio plik h zostawić bez komentarzy (można zastosować nie doxygenowskie i ich nie będzie w dokumentacji).
Ktoś ma jakieś doświadczenie w tym temacie?
Doxygen - gdzie umieszczać komentarze
Regulamin forum
Temat prosimy poprzedzić nazwą języka umieszczonego w nawiasach kwadratowych np. [Pascal].
Temat prosimy poprzedzić nazwą języka umieszczonego w nawiasach kwadratowych np. [Pascal].
Doxygen - gdzie umieszczać komentarze
Nowy blog o tematyce embedded -> https://www.embedownik.pl/
- Antystatyczny
- Geek
- Posty: 1168
- Rejestracja: czwartek 03 wrz 2015, 22:02
Re: Doxygen - gdzie umieszczać komentarze
Ja mam jedynie odrobinkę doświadczenia w doxygen. Próbowałem obu wersji komentowania. Wydaje mi się, że komentarze w nagłówkach są sensowniejsze, bo nawet po skompilowaniu softu do biblioteki będą czytelne (gdyby ktoś nie miał pliku pdf z wygenerowaną dokumentacją). Z drugiej strony nadmierna ilość komentarzy w nagłówkach nieco upośledza czytelność, bo wszędzie jest pełno komentarzy i kodów sterujących doxygenem. Pooglądaj, jak to jest zrobione np. w SPL dla STM32.
"The true sign of intelligence is not knowledge but imagination" Albert Einstein.
Re: Doxygen - gdzie umieszczać komentarze
w SPLu komentarze doxygenowskie do funkcji są tylko w plikach .C. oczywiście dla różnych makr umieszczonych w plikach .h też są doxygenowskie. Nagłówki funkcji w plikach h są wrzucone "ciurkiem" praktycznie.
Więc chyba ten sposób "przechwycę" - pasuje też do tego co pisałem - że eclipse nam ten komentarz ładnie też podpowie po najechaniu na funkcje.
Uwaga z kompilowaniem softu do biblioteki - zgadzam się w pełni, ale jakoś nigdy nie miałem potrzeby, żeby to zrobić.
Jakby ktoś miał jeszcze inne spojrzenie na to to śmiało pisać
Więc chyba ten sposób "przechwycę" - pasuje też do tego co pisałem - że eclipse nam ten komentarz ładnie też podpowie po najechaniu na funkcje.
Uwaga z kompilowaniem softu do biblioteki - zgadzam się w pełni, ale jakoś nigdy nie miałem potrzeby, żeby to zrobić.
Jakby ktoś miał jeszcze inne spojrzenie na to to śmiało pisać
Nowy blog o tematyce embedded -> https://www.embedownik.pl/
- inż.wielki
- User
- Posty: 307
- Rejestracja: niedziela 20 gru 2015, 23:11
Re: Doxygen - gdzie umieszczać komentarze
Mogę powiedzieć jak ja to realizuje podczas pracy, komentarze ogólne co do funkcji tzn co robi, parametry itd najlepiej zaraz nad funkcją. Doxygen w eclipse ma dosyć fajnego generatora, oraz te komentarze w miarę szybko się wstawia, wystarczy wpisać
/** i nacisnąć enter to jak wszystko jest dobrze podpięte eclipse automatycznie wygeneruje doxygenowy komentarz z nazwą funkcji oraz parametrami, wtedy należy po prostu dopisać jakąś szerszą definicę w tym komentarzu i następny. Jeżeli chodzi o komentarze w plikach ze źródłami, to ja ograniczam się jedynie do komentarzy odnośnie jakichś bardziej skomplikowanych kawałków i to też nie w doxygen a po prostu w pliku, bo jak potem software wychodzi na świat to tak czy siak, ktoś dostaje jedynie plik nagłówkowy oraz skompilowaną bibliotekę Mam na dzieje że nie zamotałem za bardzo. A więc reasumując:
Opis API oraz wykorzystania funkcji w plikach nagłówkowych, aby inny programista miał dokumentacje bez patrzenia w kod
Opis algorytmów lub jakichś elementów funkcji w plikach żródłowych, to jest jedynie do wglądu dla osób pracujących nad danym projektem/modułem itd.
Pozdrawiam
/** i nacisnąć enter to jak wszystko jest dobrze podpięte eclipse automatycznie wygeneruje doxygenowy komentarz z nazwą funkcji oraz parametrami, wtedy należy po prostu dopisać jakąś szerszą definicę w tym komentarzu i następny. Jeżeli chodzi o komentarze w plikach ze źródłami, to ja ograniczam się jedynie do komentarzy odnośnie jakichś bardziej skomplikowanych kawałków i to też nie w doxygen a po prostu w pliku, bo jak potem software wychodzi na świat to tak czy siak, ktoś dostaje jedynie plik nagłówkowy oraz skompilowaną bibliotekę Mam na dzieje że nie zamotałem za bardzo. A więc reasumując:
Opis API oraz wykorzystania funkcji w plikach nagłówkowych, aby inny programista miał dokumentacje bez patrzenia w kod
Opis algorytmów lub jakichś elementów funkcji w plikach żródłowych, to jest jedynie do wglądu dla osób pracujących nad danym projektem/modułem itd.
Pozdrawiam
Re: Doxygen - gdzie umieszczać komentarze
Mam dograny plugin do Eclipse o nazwie Eclox - o tym piszesz?
Też czytałem o tej opcji automatycznej formatki, jednak u mnie to nie działa Testowane na atollicu - może tu jest problem? choć nie wiem czemu. Czy coś trzeba zrobić jeszcze z tym autoformatowaniem?
Edit - znalazłem jak to uruchomić. Wszystko będzie opisane w innym wątku później.
Też czytałem o tej opcji automatycznej formatki, jednak u mnie to nie działa Testowane na atollicu - może tu jest problem? choć nie wiem czemu. Czy coś trzeba zrobić jeszcze z tym autoformatowaniem?
Edit - znalazłem jak to uruchomić. Wszystko będzie opisane w innym wątku później.
Nowy blog o tematyce embedded -> https://www.embedownik.pl/
- mokrowski
- User
- Posty: 190
- Rejestracja: czwartek 08 paź 2015, 20:50
- Lokalizacja: Tam gdzie Centymetro
Re: Doxygen - gdzie umieszczać komentarze
Tak na marginesie, coraz bardziej odchodzi się od kompilacji do funkcji binarnych włączanych na etapie konsolidacji. Czasem oczywiście jest powód ale dla małych brzdąców MCU coraz mniej.
,,Myślenie nie jest łatwe, ale można się do niego przyzwyczaić" - Alan Alexander Milne: Kubuś Puchatek
Wróć do „Inne języki programowania”
Kto jest online
Użytkownicy przeglądający to forum: Obecnie na forum nie ma żadnego zarejestrowanego użytkownika i 2 gości