Doxygen - gdzie umieszczać komentarze

[dambo]

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?

[Antystatyczny]

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.

[dambo]

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ć

[inż.wielki]

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

[dambo]

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.

[mokrowski]

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.