Namespace-Dokumentation auf einem .NET-Projekt (Sandcastle)?

Question

Ich begann mit Sandcastle vor einiger Zeit eine Dokumentation Website für eines unserer Projekte zu generieren. Es funktioniert ganz gut, aber wir haben immer nur eine schriftliche Dokumentation für Klassen, Methoden, Eigenschaften (...) in unserem Projekt und hatte völlig separate Dokumentation für das Gesamtprojekt und Projektteile / modules / Namespaces. Es wäre schön, wenn ich zusammen, dass die Dokumentation verschmelzen könnte, und fügen Sie entsprechende Dokumentation zu den generierten Hilfsdateien, aber ich kann nicht herausfinden, wie es zu tun.

Nur das Hinzufügen von Kommentaren zu der Namespace-Deklaration scheint nicht zu funktionieren (C #):

/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }

Wer weiß, wie dies zu tun? Ich weiß, es ist möglich, irgendwie, und es wäre wirklich schön zu haben ...:)

Answer 1

Sandcastle unterstützt auch die ndoc-Stil-Namespace-Dokumentation, die Sie in der Dokumentation in den Quelldateien zu bleiben erlaubt:

Erstellen Sie einfach eine nicht-öffentliche Klasse NamespaceDoc im Namespace Sie dokumentieren mögen genannt, und den XML-Doc-Kommentar für diese Klasse wird für den Namespace verwendet werden.

Schmücken Sie es mit einem [CompilerGenerated] Attribut um die Klasse zu verhindern, dass sich in der Dokumentation zeigt nach oben.

Beispiel:

namespace Some.Test
{
    /// <summary>
    /// The <see cref="Some.Test"/> namespace contains classes for ....
    /// </summary>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

Das Workitem in Sandcastle befindet sich hier.

Answer 2

Wenn Sie Sandcastle Help Builder Datei gibt es einen Dialog, um die Namespace Zusammenfassungen einzugeben. (Offenbar unterstützt auch eine bestimmte Klasse zu definieren, aber ich würde es nicht vorziehen ..)

Von der Feature-Liste:

  

Definition der Projektübersicht und   Namespace Zusammenfassung Kommentare Das wird   erscheinen in der Hilfedatei. Du kannst auch   einfach angeben, welche Namespaces   enthalten oder aus der Hilfedatei auszuschließen.   Unterstützung ist ebenfalls enthalten für   Angabe Namespace Kommentare über ein   NamespaceDoc Klasse innerhalb jeder   Namensraum.

Answer 3

Verwenden Sie Sandcastle Help File Builder . Es ermöglicht die Namespace-Beschreibungen in der XML-Projektdatei angeben

Beispiel:

<namespaceSummaryItem name="System" isDocumented="True">
    Generic interfaces and helper classes.
</namespaceSummaryItem>

Referenzen:

• Beispiel für Open-Source-Projekt dass generiert Dokumentation jeder Build (alle Skripte sind in der Stamm).
• Die wie die Dokumentation von SHFB sieht aus wie auf dem Web (es Einsatz wird auf jedem gezwungen Build)

.

Answer 4

Ich weiß, es ist eine alte Post, aber diese Hilfe zu jemand anderes sein kann.

diesen Link Nach können Sie ohne die Notwendigkeit, eine Beschreibung für die Namespaces gesetzt die Zugabe einer nicht-öffentliche Klasse zu einem Projekt.

  

die Namespace-Zusammenfassungen zu bearbeiten, erweitern Sie die Zusammenfassungen Abschnitt innerhalb der Projekteigenschaften Registerkarte in SHFB. Sie erhalten eine Einstellung mit dem Namen „NamespaceSummaries“, siehe die zunächst den Wert zeigt, „(Keine)“. Klicken Sie auf die Einstellung, um sie und eine Taste, um ein Auslassungszeichen Symbol zeigt (...) erscheint. Klicken Sie auf diese Schaltfläche, um das Namespace Zusammenfassungen Dialogfeld angezeigt werden, im Bild unten:

Answer 5

Sie können nicht Referenzen, die Art und Weise hinzufügen - tun es über NamespaceDoc.cs Instanzen

das heißt

/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary> class NamespaceDoc { }

sehen hier

Answer 6

Ich sehe Dokumentation für eine „externe XML-Kommentare Files“. Es wird ein Schema wie:

<doc>
    <assembly/>
    <members>
        <member/>
    </members>
</doc>

Wenn diese in einer separaten Datei abgelegt wird, was würde die Erweiterung sein (xml / aml) und dies kann in dem Visual Studio-Projekt verwendet werden?