Documentazione di namespace su un progetto .Net (Sandcastle)?

Question

Ho iniziato a utilizzare Sandcastle qualche tempo fa per generare un sito Web di documentazione per uno dei nostri progetti. Funziona abbastanza bene, ma abbiamo sempre scritto solo documentazione per classi, metodi, proprietà (...) nel nostro progetto e disponevamo di una documentazione completamente separata per l'intero progetto e parti / moduli / spazi dei nomi del progetto. Sarebbe bello se potessi unire quella documentazione insieme e aggiungere la relativa documentazione ai file helper generati, ma non riesco a capire come farlo.

Il semplice aggiunta di commenti alla dichiarazione dello spazio dei nomi non sembra funzionare (C #):

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

Qualcuno sa come farlo? So che è possibile in qualche modo e sarebbe davvero bello avere ... :)

Answer 1

Sandcastle supporta anche la documentazione dello spazio dei nomi in stile ndoc, che consente di incollare la documentazione nei file di origine:

Crea semplicemente una classe non pubblica chiamata NamespaceDoc nello spazio dei nomi che vuoi documentare, e il commento del documento xml per quella classe verrà usato per lo spazio dei nomi.

Adornalo con un attributo [CompilerGenerated] per impedire che la classe stessa venga visualizzata nella documentazione.

Esempio:

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

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

Si trova l'elemento di lavoro in SandCastle qui.

Answer 2

Se si utilizza Generatore di file di aiuto di Sandcastle è presente una finestra di dialogo per inserire i riepiloghi dello spazio dei nomi. (Apparentemente supporta anche la definizione di una classe specifica, ma non la preferirei ..)

Dall'elenco delle funzionalità:

  

Definizione del sommario del progetto e   commenti di riepilogo dello spazio dei nomi che lo faranno   appare nel file di aiuto. Puoi anche   indica facilmente a quali spazi dei nomi   includere o escludere dal file della guida.   È incluso anche il supporto per   specificando i commenti dello spazio dei nomi tramite a   Classe NamespaceDoc all'interno di ciascuno   namespace.

Answer 3

Utilizza File Builder di Sandcastle Help . Permette di specificare le descrizioni degli spazi dei nomi nel file di progetto XML

Esempio:

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

Riferimenti:

• esempio di progetto Open Source che genera documentazione con ogni build (tutti gli script sono nel file tronco).
• Ecco come la documentazione di SHFB sembra sul Web (esso è distribuito su ogni build forzata)

.

Answer 4

So che è un vecchio post, ma questo potrebbe essere di aiuto a qualcun altro.

Seguendo questo link , puoi impostare una descrizione per gli spazi dei nomi senza necessità di aggiungere una classe non pubblica al tuo progetto.

  

Per modificare i riepiloghi dello spazio dei nomi, espandere la sezione Riepiloghi nella scheda Proprietà progetto in SHFB. Vedrai un'impostazione chiamata & Quot; NamespaceSummaries & Quot ;, che inizialmente mostra il valore & Quot; (Nessuno) & Quot ;. Fare clic sull'impostazione per selezionarla e viene visualizzato un pulsante con un simbolo di ellissi (...). Fare clic su questo pulsante per visualizzare la finestra di dialogo Riepiloghi dello spazio dei nomi, nella foto seguente:

Answer 5

Non puoi aggiungere riferimenti in questo modo - fallo tramite le istanze di NamespaceDoc.cs

cioè

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

vedi qui

Answer 6

Vedo la documentazione per un " File di commenti XML esterni " ;. Mostra uno schema come:

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

Se questo viene inserito in un file separato, quale sarebbe l'estensione (xml / aml) e può essere utilizzata nel progetto Visual Studio?