microgeek.eu

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?

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.

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ć

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

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.

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.