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

J’ai commencé à utiliser Sandcastle il y a quelque temps pour générer un site Web de documentation pour l’un de nos projets. Cela fonctionne assez bien mais nous avons toujours écrit de la documentation pour les classes, les méthodes, les propriétés (…) dans notre projet et nous avions une documentation complètement séparée pour l’ensemble du projet et les parties / modules / espaces de noms du projet. Ce serait bien si je pouvais fusionner cette documentation et append la documentation correspondante aux fichiers d’aide générés, mais je n’arrive pas à comprendre comment le faire.

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

///  /// My short namespace description ///  namespace MyNamespace { ... } 

Est-ce que quelqu’un sait comment faire ça? Je sais que c’est possible en quelque sorte et ce serait vraiment bien d’avoir … 🙂

Sandcastle prend également en charge la documentation de l’espace de noms ndoc-style, qui vous permet de coller la documentation dans les fichiers source:

Créez simplement une classe non publique appelée NamespaceDoc dans l’espace de noms que vous souhaitez documenter, et le commentaire de la documentation xml pour cette classe sera utilisé pour l’espace de noms.

Ornez-le avec un atsortingbut [ComstackrGenerated] pour éviter que la classe elle-même n’apparaisse dans la documentation.

Exemple:

 namespace Some.Test { ///  /// The  namespace contains classes for .... ///  [System.Runtime.ComstackrServices.ComstackrGenerated] class NamespaceDoc { } } 

L’élément de travail dans SandCastle se trouve ici.

Si vous utilisez Sandcastle Help File Builder, il existe une boîte de dialog pour entrer les résumés Namespace. (Apparemment aussi, soutien à la définition d’une classe spécifique, mais je ne le préférerais pas ..)

De la liste des fonctionnalités:

Définition du résumé du projet et des commentaires récapitulatifs des espaces de noms qui apparaîtront dans le fichier d’aide. Vous pouvez également indiquer facilement les espaces de noms à inclure ou à exclure du fichier d’aide. Une prise en charge est également incluse pour spécifier des commentaires d’espace de noms via une classe NamespaceDoc dans chaque espace de noms.

Utilisez Sandcastle Help File Builder . Il permet de spécifier les descriptions des espaces de noms dans le fichier de projet XML

Exemple:

  Generic interfaces and helper classes.  

Les références:

  • exemple de projet Open Source qui génère de la documentation à chaque version (tous les scripts sont dans le tronc).
  • Voilà comment la documentation de SHFB se présente sur le Web (elle est déployée à chaque génération forcée)

.

Je sais que c’est un ancien message, mais cela peut aider quelqu’un d’autre.

En suivant ce lien , vous pouvez définir une description pour les espaces de noms sans avoir à append une classe non publique à votre projet.

Pour modifier les résumés d’espace de noms, développez la section Résumés dans l’onglet Propriétés du projet dans 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 dialog Résumé des espaces de noms, illustrée ci-dessous:

entrer la description de l'image ici

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

c’est à dire

///

/// Concrete implementation of see cref="IInterface" using see cref="Concrete"
///

class NamespaceDoc { }

vois ici

Je vois la documentation pour un “Fichiers de commentaires XML externes”. Afficher un schéma comme:

       

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