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

Question

Existe-t-il une convention standard (comme phpdoc ou la docstring de python) pour commenter le code C# afin que la documentation de classe puisse être automatiquement générée à 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 cela sont :

Doc Fantôme, qui donnent une seule touche de raccourci pour générer automatiquement des commentaires pour une classe ou une méthode.Château de sable, 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

Microsoft utilise "Commentaires sur la documentation XML" 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 4

Les réponses précédentes soulignent parfaitement la syntaxe XML.Je voulais juste ajouter ma recommandation pour le générateur de bibliothèque d'aide nDoc gratuit (et open source) qui analyse tous les commentaires d'un projet.

Answer 5

C# a intégré commandes de documentationAmusez-vous!

Answer 6

On m'a toujours dit d'utiliser des commentaires de bloc ouverts avec 2 astérisques ou plus pour délimiter les commentaires de documentation.

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