Documentation sur les espaces de noms sur un projet .Net (Sandcastle)?

Question

J'ai commencé à utiliser Sandcastle pour générer un site Web de documentation pour l'un de nos projets. Cela fonctionne assez bien, mais nous n’avons toujours reçu que de la documentation écrite pour les classes, méthodes, propriétés (...) de notre projet et nous avions une documentation complètement séparée pour le projet global et les parties / modules / espaces de nom du projet. Ce serait bien si je pouvais fusionner cette documentation et ajouter une documentation respective aux fichiers d'aide générés, mais je ne sais pas comment le faire.

Le simple ajout de commentaires à la déclaration d'espace de noms ne semble pas fonctionner (C #):

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

Quelqu'un sait-il comment faire cela? Je sais que c'est possible d'une manière ou d'une autre et que ce serait vraiment bien d'avoir ...:)

Answer 1

Sandcastle prend également en charge la documentation sur les espaces de noms de style ndoc, qui vous permet de coller la documentation dans les fichiers sources:

Créez simplement une classe non publique appelée NamespaceDoc dans l'espace de noms que vous souhaitez documenter, et le commentaire doc XML de cette classe sera utilisé comme espace de noms.

Portez-le avec un attribut [CompilerGenerated] pour empêcher la classe elle-même de s'afficher dans la documentation.

Exemple:

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

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

L'élément de travail dans SandCastle est situé ici.

Answer 2

Si vous utilisez le constructeur de fichiers d’aide Sandcastle , une boîte de dialogue vous permet de saisir les résumés des espaces de noms. (Apparemment, supporte aussi la définition d'une classe spécifique, mais je ne le préférerais pas.)

Dans la liste des fonctionnalités:

  

Définition du résumé du projet et   commentaires de résumé d'espace de noms qui   apparaissent dans le fichier d'aide. Vous pouvez également   indiquer facilement les espaces de noms à   inclure ou exclure du fichier d'aide.   Le support est également inclus pour   spécifier des commentaires d'espace de noms via un   NamespaceDoc class dans chaque   espace de noms.

Answer 3

Utilisez le constructeur de fichiers d’aide Sandcastle . Il permet de spécifier des descriptions d’espaces de noms dans le fichier de projet XML

Exemple:

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

Références:

• exemple de projet Open Source qui génère de la documentation avec chaque construction (tous les scripts sont dans le le coffre).
• C’est la comment la documentation est SHFB se présente comme sur le Web (il est déployé sur chaque build forcé)

.

Answer 4

Je sais que c'est un ancien message, mais cela peut être utile à quelqu'un d'autre.

En suivant ce lien , vous pouvez définir une description des espaces de nom sans qu'il soit nécessaire d'ajouter une classe non publique à votre projet.

  

Pour modifier les résumés des espaces de noms, développez la section Résumés dans l'onglet Propriétés du projet de SHFB. Vous verrez un paramètre nommé & "; NamespaceSummaries &" ;, qui affiche initialement la valeur, & "; (Aucun) &"; Cliquez sur le paramètre pour le sélectionner et un bouton affichant un symbole de points de suspension (...) apparaît. Cliquez sur ce bouton pour afficher la boîte de dialogue Résumés des espaces de noms, illustrée ci-dessous:

Answer 5

Vous ne pouvez pas ajouter de références de cette façon - faites-le via les instances NamespaceDoc.cs

c'est-à-dire

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

voir ici

Answer 6

Je vois la documentation d'un " Fichier de commentaires XML externes " ;. Afficher un schéma tel que:

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

Si ceci est placé dans un fichier séparé, quelle serait l'extension (xml / aml) et cela pourrait-il être utilisé dans le projet Visual Studio?