Wie soll ich meinen C # -Code zu dokumentieren? [geschlossen]

Question

Ich baue die Dokumentation für unsere C # API enthalten:

1. Eine allgemeine Übersicht und Beschreibung des aktuellen Status als doc / pdf-Datei.
2. Ein Klassenbibliothek-API in einer CHM-Datei mit Sandcastle.

Fragen:

1. Sollte ich diese zwei in die gleiche CHM-Datei zusammenführen? Was ist ein guter Weg, um sie zu verschmelzen?
2. muss ich bestimmte Klassen / Pakete auszuschließen. Wie kann ich das in Sandcastle angeben?
3. Sie erzeugt Dokumentation für den VB-Code und dem Visual C ++ Code. Wie kann ich das ändern? Oder soll ich es lassen, wohl wissend, dass ich nur sicheren Code verwenden?
4. Wo kann ich HTML-Hilfe-2.x-Viewer-Pfad auf meinem System?

Edit:

Die Kommentare, die ich über Methoden, Feldern und Klassen vornehmen, werden in der Dokumentation nicht erzeugt wird.

Was soll ich tun?

Answer 1

ich empfehlen, dass Sie Sandcastle Help File Builder von Codeplex. Sie können ganz einfach schließen und Namespaces ausschließen, aber ich bin nicht sicher, wie eine einzige Klasse über ohne gehen. Sie können die Option auf nur Dokumentation für öffentliche / geschützte Klassen zu generieren, aber ich weiß nicht, ob das Ihr Szenario passt.

Sie können auch eine bestimmte Sprache in SHFB, wie zu Ihrer zweiten Frage Ziel.

Darüber hinaus können Sie MAML innerhalb SHFB für die konzeptionelle Dokumentation verwenden, wie Sie erwähnen, wie sie in der doc / pdf-Datei zu sein. Sie sollten Doc2Maml nutzen können für die Migration bestehender Dokumentation. Doc2Maml ist ein Teil des DocProject, aber es scheint, dass Sie es als Einzellösung könnte der Lage sein.

Bearbeiten in Reaktion auf einen Kommentar:

Wegbeschreibung sind für SHFB 1.8.0.1. Ich erinnere mich nicht genau so, wie es in 1.7 zu tun, aber ich glaube, es ist ähnlich:

1. Unter „Kommentare“ Gruppe im Projekt-Registerkarte Eigenschaften, klicken Sie auf die Ellipsen rechts von „NamespaceSummaries“.
2. In der Checkbox-Liste in der oberen linken, deaktivieren Sie alle Namespace Sie ausschließen möchten.

Dies ist auch der Bildschirm, wo Sie Namespace-Zusammenfassungen in.

Answer 2

Neben Sand Castle, wie oben erwähnt, würde ich auch empfehlen, sich unter FxCop und StyleCop , um sicherzustellen, dass Ihr Code und Dokumentation bis zu CLS Compliance ist Standards.

Answer 3

Sandcastle Help File Builder (SHFB) selbst hat eine CHM-Datei, wo Sie die Antworten auf die Fragen finden wie: „Wie kann ich bestimmte Namensräume oder Klassen aus dem erzeugten doc ausschließen?“

Sie mögen denken, ich die Antwort wissen, und ich bin sein snarky durch Sie nicht zu sagen. Nicht wahr. Aber ich war die doc gestern Abend Skimming und sah einen Eintrag auf diesem Thema.

Ich weiß nicht, warum Sie sich nicht nur in den VB und C ++ Sachen verlassen; da sein in der Zukunft kann jemand, der eine Sprache verwendet, die (schockierend) ist nicht C # mit Ihrer Bibliothek. Die Sprache ist in der Regel einstellbar durch den Hilfe-Viewer, so C # Devs die VB-Syntax ignorieren kann.

Wie für die Zusammenführung, hat SHFB einen Mechanismus in beliebiger HTML in einer beliebigen Hierarchie hinzuzufügen. In der GUI ist es hier:

http://www.freeimagehosting.net/uploads/7de19ea568.jpg

diese verwenden, können Sie die PDF / DOC konvertieren in HTML und dann einbetten es nur in der CHM.