. Standard XML de documentation

Question

J'ai regardé les questions connexes suggérées mais aucune d'elles n'est ce que je cherche. En tant que nouveau développeur, j'essaie de suivre les meilleures pratiques et la documentation est importante. Comme je vais, j'essaie de créer des documents XML dans mon code. J'ai découvert le plug-in GhostDoc qui permet d'accélérer cela.

Ma question cependant est; Existe-t-il une norme généralement exclue quant à ce qui devrait être inclus dans le XML. Par défaut j'utilise <Summary><Param><Returns> le cas échéant. Y en at-il d'autres? Devrais-je inclure l'auteur? Comment? <Patrick></Patrick>? Est-ce que <Remarks> vaut la peine?

Je serais reconnaissant pour toute indication à ce sujet. Je vous remercie!

Answer 1

Je ne récemment trouvé this guide to XML documentation. C'est vraiment pratique. Ce n'est pas un guide de bonnes pratiques en tant que tel, mais il est bon pour couvrir les étiquettes qui ne sont pas utilisées très souvent et donc oubliées.

Answer 2

Je pense vraiment que l'étiquette <remarks> vaut le temps, car elle vous permet d'élaborer sur le résumé, et plus de connaissances est toujours une bonne chose.

Je pense aussi que le <typeparamref> est important pour les classes génériques.

À l'intérieur de chacun de vos éléments, vous devez également utiliser la balise <see>, de sorte que vous puissiez lier la documentation ensemble.

En dehors des balises standard, j'ajoute <author> pour montrer l'auteur original de la classe/méthode/propriété/etc, ainsi qu'une balise <created> pour indiquer quand le membre a été créé. Dans un environnement d'équipe, vous voudrez probablement quelque chose de plus robuste, comme ceci:

<revisions> 
    <revision> 
    <author>Nicholas Paldino</author> 
    <revised>2009-02-01</revised> 
    </revision> 
    <revision> 
    <author>Mr_Mom</author> 
    <revised>2009-02-11</revised> 
    </revision> 
</revisions>