Les chaînes de documentation C#: Paramètre d'une propriété d'action

Question

Je suis en train de documenter du code c# en ce moment. J'ai cette interface qui expose une propriété Action.

interface IFoo
{
    /// 
    /// Sera appelé lorsqu'un Bar se produit
    /// 
    /// 
    /// Peut être une chaîne de caractères ou null.
    /// Si ce n'est pas null, le message doit être affiché.
    /// Si c'est null, le message doit être effacé.
    /// 
    Action OnBarHappened { get; set; }
}

J'aimerais documenter le paramètre qui sera donné à l'Action. Évidemment, mon balise nommée de façon sensible, action_parameter_1_or_something, n'existe pas.

Comment documenteriez-vous cela ?

Answer 1

J'utilise Sandcastle Help File Builder pour créer mes documents. J'ai en fait rencontré exactement le même problème que vous. SHFB ne le prend pas en charge dès le départ, mais j'ai un problème dans lequel j'explique comment j'ai personnellement ajouté ces balises à la sortie de ce qu'il a fait. En gros, vous devez ajouter votre balise à quelques transformations XML, puis elle apparaîtra dans votre documentation.

https://github.com/EWSoftware/SHFB

https://github.com/EWSoftware/SHFB/issues/199

C'est le problème spécifique que j'avais signalé. Cela apparaît alors automatiquement dans notre documentation API et peut être utilisé pour inclure n'importe quel jeu de balises que nous utilisons. L'une des choses pour lesquelles nous l'utilisons est le type de données, m, m/s, m^3 etc.

Answer 2

D'après ce que vous avez expliqué dans les commentaires, je vais essayer de vous donner une réponse... Commencez par le concept de ce que représente la propriété et de ce qu'elle fait. Donnez un nom à votre propriété en fonction de cela. Ensuite, utilisez les balises du site MSDN (https://msdn.microsoft.com/en-us/library/5ast78ax.aspx) pour mettre vos explications dans le format que vous préférez. Personnellement, je placerais simplement une brève description dans le bloc de résumé. Vous ne voulez pas trop prolonger la documentation d'une propriété. Par exemple : "Normalement une chaîne de caractères. Si null, fait XYZ".