Existe-t-il un standard (comme phpdoc ou docstring de python) pour commenter le code C#?

Question

Existe-t-il une convention standard (comme phpdoc ou docstring de python) pour commenter le code C# afin que la documentation de classe puisse être générée automatiquement à partir du code source?

Answer 1

Vous pouvez utiliser des commentaires de style XML et utiliser des outils pour extraire ces commentaires dans la documentation de l'API.

Voici un exemple du style de commentaire:

/// <summary> 
/// Authenticates a user based on a username and password. 
/// </summary> 
/// <param name="username">The username.</param> 
/// <param name="password">The password.</param> 
/// <returns> 
/// True, if authentication is successful, otherwise False. 
/// </returns> 
/// <remarks> 
/// For use with local systems 
/// </remarks> 
public override bool Authenticate(string username, string password) 

Certains éléments pour faciliter ce sont:

GhostDoc, qui donnent une seule touche de raccourci pour générer automatiquement des commentaires pour une classe ou une méthode. Sandcastle, qui génère une documentation de style MSDN à partir de commentaires XML.

Answer 2

/// <summary> 
/// 
/// </summary> 
/// <param name="strFilePath"></param> 

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

Answer 3

C# a construit dans documentation commands Amusez-vous!

Answer 4

Microsoft utilise "XML Documentation Comments" qui donnera des descriptions IDE Intellisense et vous permettra également de générer automatiquement une documentation de style MSDN à l'aide d'un outil tel que Sandcastle si vous activez la génération de la sortie du fichier XML.

Pour activer la génération du fichier XML pour la documentation, faites un clic droit sur un projet dans Visual Studio, cliquez sur "Propriétés" et allez dans l'onglet "Build". Vers le bas, vous pouvez spécifier un emplacement pour votre fichier de sortie de commentaires XML.

Answer 5

Les réponses précédentes soulignent parfaitement la syntaxe XML. Je voulais juste jeter dans ma recommandation pour le free (and open-source) nDoc help library generator qui analyse tous les commentaires dans un projet.

Answer 6

On m'a toujours dit d'utiliser des commentaires de bloc ouverts avec 2 ou plusieurs astérisques qui délimitent les commentaires de la documentation.

/** 
Documentation goes here. 
(flowerboxes optional) 
*/