Existe-t-il des directives de style publiées pour la documentation C# XML?

Question

Je demande à mes développeurs qui écrivent du code C# de suivre les directives de StyleCop. C'est génial pour le code, mais j'ai presque toujours des questions sur la documentation (ok ... ok ... donc personne ne demande, parce que les programmeurs ont tendance à détester la documentation). Je pourrais suggérer de copier le style de MSDN, mais je suis curieux de savoir si Microsoft ou quelqu'un d'autre a publié quelque chose à ce sujet.

Par exemple, les constructeurs sont documentés comme suit. Je n'essaie pas de susciter un débat sur la façon dont la documentation devrait être écrite, ici. Je suis à la recherche de quelques lignes directrices publiées sur la syntaxe suggérée pour la documentation.

Merci d'avance!

Answer 1

StyleCop FxCop fournit également des règles pour la documentation XML. Si vous ne suivez pas le modèle défini par un certain ensemble de règles, il se plaindra.

Ce sont toutes les règles SA1600-SA1647.

Par exemple, la règle SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText stipule que:

Le résumé d'un constructeur d'instance non-privé doit commencer par « Initialise une nouvelle instance de la classe {nom de classe}. »

Pour plus d'informations, voir FxCop.

Answer 2

Si vous voulez un guide général sur comment et où la documentation XML doit être utilisée, voici deux liens très utiles (auxquels j'ai fait référence à plusieurs reprises).

• MSDN Recommended Tags for Documentation Comments
• C# XML Documentation : Alan Dean (mort - archived version)

Je suppose que cela est vaguement le genre de chose que vous recherchez. En ce qui concerne la formulation et la grammaire des commentaires XML, j'ai moi aussi cherché des conseils/des directives à ce sujet, mais en vain. La meilleure idée à cet égard est simplement de suivre le .NET BCL (Bibliothèque de classes de base) - bien qu'il y ait une incohérence étrange même dans la documentation BCL.

espoir qui aide ...

Answer 3

Mon visual studio add-in, AtomineerUtils, va générer et mettre à jour des commentaires de XMLDoc.

Il a un ensemble de modèles qui vous permettent de spécifier le style exact (quelles entrées sont légales pour différents types d'éléments de code, dans quel ordre ils sont listés, s'il y a des lignes vides entre certaines entrées et le style du bloc de documentation englobant). Il supprimera les entrées qui ne sont plus correctes (par exemple supprimer des paramètres) et ajoutera des entrées pour des fonctionnalités non documentées (par exemple de nouveaux paramètres ou des exceptions levées) et conservera la documentation en utilisant l'indentation automatique et l'encapsulation de mots. Ainsi, en utilisant AU pour générer et mettre à jour vos commentaires, vous pouvez très facilement appliquer un style et une disposition spécifiques pour vos commentaires de documentation.Si vous souhaitez utiliser StyleCop pour appliquer certaines règles de documentation, AtomineerUtils a la possibilité de produire de la documentation dans un format compatible StyleCop.

Il permet également de façon rapide et facile à documenter le code que même les programmeurs moins disposés dans votre équipe seront beaucoup plus susceptibles de bien documenter leur code.