Doc-Zeichenfolge-Einrichtung in C++

Question

Sprachen wie Python, MATLAB, E-Lisp haben diese nette Einrichtung für Doc-Strings. Mit dieser Funktion können Sie mit nur wenigen Tastenanschlägen im Terminal die Dokumentationen der Funktionen/Module abrufen, die Sie geschrieben und in Ihren Code importiert haben.

Jetzt gibt es eine „Technik“ (Bibliothek, Editor Tricks, was auch immer zu) eine ähnliche Einrichtung in C++/C erhalten nehme ich die Dokumentation der Funktion innerhalb der Quelldatei an den Kopf der Funktion enthalten , dann würde ich gerne einen Befehl wie getinfo am Terminal eingeben. (etwas wie eine Manpage)

Ich weiß, dass eine solche "Mann" -Funktion für viele C-Funktionen existiert, aber die Dokumentation für diese Funktionen sind in separaten Textdateien aus dem Quellcode geschrieben. Ich möchte, dass die Dokumentation an Ort und Stelle ist

Answer 1

Sie können etwas wie Doxygen verwenden. Es hat Unterstützung für die Generierung von man pages, neben anderen Formaten.

Answer 2

Wenn Sie Ihren Code mit Kommentaren in einer Javadoc-ähnlichen Syntax notieren, können Sie eine Dokumentation für Ihren Code in verschiedenen Formaten mit Doxygen generieren. Es kann unter anderem Manpages erzeugen, aber es scheint, dass das bevorzugte Ausgabeformat HTML-Seiten sind.

Answer 3

Visual Studio kann Popups erstellen, die Informationen enthalten, die aus DocXml formatierten Kommentaren extrahiert wurden. Sie müssen mit /doc kompilieren, die das XML aus den Kommentaren in eine Datei extrahieren. Dann müssen Sie xdcmake ausführen, um die Dateien in eine XML-Datei zu kompilieren. Normalerweise würden Sie all dies automatisch im Build-Prozess handhaben, so dass Sie nicht viel manuell erledigen müssen (außer natürlich, die Kommentare selbst zu schreiben). Beachten Sie jedoch, dass der Code (zumindest eine Deklaration) erstellt werden muss, bevor Sie die Popups erhalten.

Ich fühle mich verpflichtet, dass IMO hinzufügen, die meisten solcher Kommentare sind in der Regel ziemlich nah an nutzlos. Wenn ein Unternehmensstandard sie unvermeidbar macht, sei es so - aber wenn sie ehrlich irgendwelche nützlichen Informationen zur Verfügung stellen, würde ich das als Hinweis auf ein Problem betrachten ("Code smell", wenn du diesen Wortlaut bevorzugst). In den meisten Fällen sollte die Kombination aus dem Namen der Funktion (oder was auch immer) und den Namen/Typen der Parameter die Verwendung der Funktion ziemlich klar machen.