Ich habe eine kleine C-Bibliothek für Linux und FreeBSD geschrieben und werde die Dokumentation dafür schreiben. Ich habe versucht, mehr über das Erstellen von Manpages zu erfahren, habe jedoch keine Anweisungen oder Beschreibungen für Best Practices zum Erstellen von Manpages für Bibliotheken gefunden. Insbesondere interessiert mich welcher Abschnitt, um Manpages der Funktionen zu setzen? 3? Vielleicht gibt es gute Beispiele oder Handbücher? Manpages für jede Funktion aus der Bibliothek erstellen eine schlechte Idee?
12
manzum Programmieren, außer für Standardbibliotheken und Systemaufrufe.Antworten:
Handbuchseiten für eine Bibliothek werden in Abschnitt 3 behandelt.
Denken Sie für gute Beispiele für Handbuchseiten daran, dass einige mit bestimmten Details von groff geschrieben wurden und / oder bestimmte Makros verwenden, die nicht wirklich portierbar sind.
Es gibt immer einige Fallstricke bei der Portierbarkeit von Manpages, da einige Systeme möglicherweise spezielle Funktionen verwenden (oder auch nicht). Beispielsweise musste
dialogich bei der Dokumentation Unterschiede in verschiedenen Systemen berücksichtigen (und umgehen), um Beispiele anzuzeigen (die nicht gerechtfertigt sind).Beginnen Sie mit dem Lesen der entsprechenden Abschnitte ,
man manwo es die Standard - Makros erwähnt, und vergleicht diese Beschreibungen für FreeBSD und Linux.Ob Sie eine Handbuchseite für die Bibliothek oder separate Handbuchseiten für die Funktionen (oder Funktionsgruppen) erstellen, hängt davon ab, wie kompliziert die Beschreibungen der Funktionen wären:
Weitere Lektüre:
quelle
Ich benutze Ronn . Sie schreiben einfach Markdown und es wird eine Manpage daraus. Es gibt auch einen (etwas weniger fähigen) Klon, den Marked -Man .
Ich habe meine Skripte damit dokumentiert, indem ich
END_MANabgegrenzte Heredocs und meinen C / C ++ - Code verwendet habe, indem ich dieselbenEND_MANabgegrenzten Heredocs mit Ausnahme von innerhalb verwendet habe/* */. Entweder ist es einfach mit sed zu extrahieren und dann in eine Manpage zu rendern. (Mit ein wenig UNIX-Signalhackery und inotifywait können Sie Ihre Manpage-Abschnitte live extrahieren und anzeigen und den Manpage-Browser neu laden, während die Quelle aktualisiert wird.)Was den Abschnitt betrifft, dann wäre 3 dies für eine C-Bibliothek auf Benutzerebene. Sie können über die Abschnittsnummern (unter anderem) in man (1) lesen .
Wenn Sie lesbare, gut strukturierte Manpages mit Beispielen sehen möchten, werfen Sie einen Blick auf die Plan9- Bibliotheken unter https://swtch.com/plan9port/unix/, in denen Sie sehen können, wie die eigentlichen Ersteller von
cundUNIXund deren Dokumentation vorgehen System wahrscheinlich dafür gedacht, dass diese Dinge funktionieren.quelle
Ergänzend zu den anderen Antworten können Sie auch reStructuredText und den Befehl rst2man verwenden, der Teil des Pakets python-docutils ist .
Diese Abschriftensprache wurde von Python für die Dokumentation übernommen und ist viel einfacher zu erlernen, zu schreiben und zu warten als die guten alten troff man-Makros, die rst2man aus Ihrem reStructuredText für Sie generiert.
quelle
Sie können die API mit doxygen dokumentieren , um die Referenz als HTML bereitzustellen, und Manpages und andere Formate für das Offline-Lesen generieren.
Der Vorteil von doxygen ist, dass es sich um eine Art "Inline" -Dokumentation wie JavaDoc oder PythonDoc handelt, die als Schnittstellenkommentare fungiert (oder vv. Kommentare, die als Dokumententext fungieren). Sie fügen die Dokumententexte zu Ihren Quell- / Header-Dateien hinzu und extrahieren sie von dort, wodurch sich die Wahrscheinlichkeit erhöht, dass sie auf dem neuesten Stand sind.
quelle