Doxygen - gdzie umieszczać komentarze

Tutaj umieszczamy tematy związane z językami programowania niepasującymi do innych działów.
Regulamin forum
Temat prosimy poprzedzić nazwą języka umieszczonego w nawiasach kwadratowych np. [Pascal].
Awatar użytkownika
dambo
Expert
Expert
Posty: 534
Rejestracja: czwartek 17 mar 2016, 17:12

Doxygen - gdzie umieszczać komentarze

Postautor: dambo » niedziela 02 kwie 2017, 14:45

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?
Zapraszam na mojego pseudobloga z projektami itp: http://projektydmb.blogspot.com/

Awatar użytkownika
Antystatyczny
Expert
Expert
Posty: 976
Rejestracja: czwartek 03 wrz 2015, 22:02

Re: Doxygen - gdzie umieszczać komentarze

Postautor: Antystatyczny » niedziela 02 kwie 2017, 14:50

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.

Awatar użytkownika
dambo
Expert
Expert
Posty: 534
Rejestracja: czwartek 17 mar 2016, 17:12

Re: Doxygen - gdzie umieszczać komentarze

Postautor: dambo » niedziela 02 kwie 2017, 15:07

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ć :)
Zapraszam na mojego pseudobloga z projektami itp: http://projektydmb.blogspot.com/

Awatar użytkownika
inż.wielki
User
User
Posty: 176
Rejestracja: niedziela 20 gru 2015, 23:11

Re: Doxygen - gdzie umieszczać komentarze

Postautor: inż.wielki » niedziela 02 kwie 2017, 20:32

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

Awatar użytkownika
dambo
Expert
Expert
Posty: 534
Rejestracja: czwartek 17 mar 2016, 17:12

Re: Doxygen - gdzie umieszczać komentarze

Postautor: dambo » niedziela 02 kwie 2017, 20:41

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.
Zapraszam na mojego pseudobloga z projektami itp: http://projektydmb.blogspot.com/

Awatar użytkownika
mokrowski
User
User
Posty: 138
Rejestracja: czwartek 08 paź 2015, 20:50
Lokalizacja: Tam gdzie Centymetro

Re: Doxygen - gdzie umieszczać komentarze

Postautor: mokrowski » poniedziałek 03 kwie 2017, 00:12

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 1 gość