Doc string facility w C++

Question

Języki takie jak Python, MATLAB, E-Lisp mają tę fajną funkcję dla doc-stringów. Za pomocą tej funkcji za pomocą kilku naciśnięć klawiszy w terminalu można pobrać dokumentacje funkcji/modułów, które zostały napisane i zaimportowane do kodu.

Teraz jest jakiś „technika” (biblioteka, sztuczki Editor, niezależnie od celu), aby uzyskać podobny obiekt w C++/C Załóżmy, że zawierają dokumentację funkcji w pliku źródłowego w głowę funkcji , , a następnie chciałbym wpisać polecenie takie jak getinfo na terminalu. (coś w stylu jak strona podręcznika)

Wiem, że taka funkcja "człowiek" istnieje dla wielu funkcji języka C, ale dokumentacja tych funkcji jest zapisana w osobnych plikach tekstowych z kodu źródłowego. Chciałbym, aby dokumentacja była na miejscu.

Answer 1

Możesz użyć czegoś takiego jak Doxygen. Obsługuje generowanie między innymi formatów man pages.

Answer 2

Jeśli notujesz swój kod z komentarzami w składni podobnej do Javadoc, możesz wygenerować dokumentację dla swojego kodu, w różnych różnych formatach, używając Doxygen. Może generować, między innymi, strony podręcznika, ale wydaje się, że preferowanym formatem wyjściowym, którego używają ludzie, są strony HTML.

Answer 3

Visual Studio może/będzie generować wyskakujące okienka zawierające informacje wyodrębnione z DocXml sformatowanych komentarzy. Musisz skompilować z /doc, który wyodrębni XML z komentarzy do pliku .xdc. Następnie musisz uruchomić xdcmake, aby skompilować pliki .xdc do pliku xml. Zwykle radzisz sobie z tym automatycznie w procesie kompilacji, więc nie musisz robić zbyt wiele ręcznie (oczywiście z wyjątkiem pisania samych komentarzy). Należy jednak pamiętać, że kod (przynajmniej deklaracja) musi zostać skompilowany, zanim pojawią się wyskakujące okienka.

Czuję się zobowiązany do dodania, że ​​IMO, większość takich komentarzy jest na ogół dość blisko bezużyteczne. Jeśli standard korporacyjny sprawia, że ​​są nieuniknione, niech tak będzie - ale jeśli szczerze dostarczają użytecznych informacji, uznałbym to za oznakę problemu ("zapach kodu", jeśli wolisz takie sformułowanie). W większości przypadków połączenie nazwy funkcji (lub cokolwiek innego) z nazwami/typami parametrów powinno spowodować, że użycie tej funkcji jest całkiem jasne.