Documents XML .NET - hériter de la documentation

Question

NDoc possède un élément XML inheritdoc qui vous permet d'hériter de la documentation d'un membre de la classe parent (ou d'une interface implémentée). Cependant, Visual Studio (c.-à-d. Le compilateur C #) ne comprend pas cette balise et se plaint de l'absence de documentation ou de documentation complète. Il en va de même de StyleCop et de quelques autres outils. Y a-t-il une approche alternative? Comment procédez-vous pour que la documentation reste complète sans pour autant dupliquer les descriptions XML?

Answer 1

Une autre solution consiste à utiliser GhostDoc , un complément pour Visual Studio qui génère automatiquement commentaires pour vous. Cela duplique bien sûr la description XML, ce qui fait partie de ce que vous essayez d'éviter - mais au moins, elle le fait automatiquement pour vous.

Que se passe-t-il si vous laissez simplement la documentation entièrement pour les méthodes héritées ou les méthodes d'interface? Je suppose que cela dépend de la façon dont vous avez configuré NDoc, mais la documentation MSDN semble bien entendu hériter naturellement de la documentation - et une vérification rapide suggère que VS ne se plaindra pas si vous ne produisez pas docs pour une méthode héritée. La peine d'essayer, certainement.

Answer 2

J'ai une meilleure réponse: FiXml .

Cloner des commentaires avec GhostDoc est certes une approche efficace, mais présente des inconvénients importants, par exemple:

• Lorsque le commentaire d'origine est modifié (ce qui arrive fréquemment au cours du développement), son clone n'est pas.
• Vous produisez une énorme quantité de doublons. Si vous en utilisez outils d’analyse de code source (par exemple, Duplicate Finder dans Team City), il retrouvez principalement vos commentaires.

Brève description de FiXml: il s’agit d’un post-processeur de documentation XML produit par C # \ Visual Basic .Net. Il est implémenté en tant que tâche MSBuild, il est donc très facile de l'intégrer à n'importe quel projet. Il aborde quelques cas gênants liés à la rédaction de documentation XML dans les langues suivantes:

• Absence de prise en charge de l'héritage de la documentation à partir d'une classe ou d'une interface de base. I.e. la documentation de tout membre substitué doit être écrite à partir de zéro, bien qu'il soit normalement & # 8217; assez souhaitable d'hériter au moins de sa partie.
• Absence de prise en charge de l'insertion de modèles de documentation couramment utilisés , tels que & # 8220; ce type est singleton - utilisez sa propriété <see cref="Instance" /> pour en obtenir la seule instance. & # 8221 ;, ou même & # 8220; Initialise une nouvelle instance de <CurrentType> classe. & # 8221;

Pour résoudre les problèmes mentionnés, les balises XML supplémentaires suivantes sont fournies:

• <inheritdoc />, <inherited /> tags
• <see cref="..." copy="..." /> attribut dans <see/> balise.

Voici sa page Web et page de téléchargement (liens rompus).

Enfin, il y a <inheritdoc> une balise dans Sandcastle - c'est Mieux vaut l'utiliser que de copier des commentaires XML, mais il présente peu d'inconvénients par rapport à FiXml:

• Sandcastle produit des fichiers d’aide HTML compilés - il ne modifie pas les .xml fichiers contenant des commentaires XML extraits. Mais ces fichiers sont utilisés par de nombreux outils, notamment .NET Reflector et le navigateur de classes \ IntelliSense dans Visual Studio .NET. Donc, si vous utilisez uniquement Sandcastle, vous ne verrez pas la documentation héritée ici.
• La mise en œuvre de Sandcastle est moins puissante. Par exemple. le n'est pas <see ... copy="true" />.

Voir Description de Sandcastle pour plus de détails.

Answer 3

J'ai construit un outil de ligne de commande pour post-traiter les fichiers de documentation XML afin d'ajouter la prise en charge de < inheritdoc / > tag.

Cela n'aide pas Intellisense dans le code source, mais permet aux fichiers de documentation XML modifiés d'être inclus dans un package NuGet et fonctionne donc avec Intellisense dans les packages NuGet référencés.

Voir www.inheritdoc.io pour plus de détails (version gratuite disponible).