Modes de synchronisation de l'interface et la mise en œuvre des commentaires en C#

Sont là automatique des moyens pour synchroniser les commentaires entre une interface et sa mise en œuvre?
Je suis en train de documenter à la fois et ne voudrais pas manuellement les garder synchronisés.

Mise à JOUR:

Considérer ce code:

interface IFoo{
    ///<summary>
    ///Commenting DoThis method
    ///</summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Quand je créer une classe comme ceci:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Ici les commentaires ne sont pas affichés:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

La <inheritDoc/> balise parfaitement générer la documentation en Château de Sable, mais il ne fonctionne pas dans intellisense les info-bulles.

Merci de partager vos idées.

Grâce.

l'ajout de la documentation de la balise
Les albums de cette fonctionnalité de mise en œuvre? visualstudio.uservoice.com/forums/121579-visual-studio/...
Comment puis-je faire Atomineer Pro pour laisser générer des <inheritDoc/> documentation de la balise pour la mise en œuvre si la documentation de l'interface est disponible?
Vous avez raison <inheritdoc/> est cassé dans Visual Studio. Merci de voter pour le rapport de bug visualstudio.uservoice.com/forums/121579-visual-studio/...

InformationsquelleAutor Valentin | 2009-05-05

c#documentation xml-documentation

56

Vous pouvez le faire assez facilement à l'aide de Microsoft de Châteaux de sable (ou NDoc) inheritdoc tag. Il n'est pas officiellement pris en charge par le cahier des charges, mais les balises personnalisées sont parfaitement acceptables, et en effet, Microsoft a choisi de copier ce (et un ou deux autres balises) à partir de NDoc, lors de la création de Châteaux de sable.
```
///<inheritdoc/>
///<remarks>
///You can still specify all the normal XML tags here, and they will
///overwrite inherited ones accordingly.
///</remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}
```
Ici est la page d'aide de Sandcastle Help File Builder interface utilisateur, ce qui explique son utilisation dans son intégralité.

(Bien sûr, ce n'est pas spécifiquement "synchronisation", comme votre question le mentionne, mais il semble être exactement ce que vous cherchez tout de même.)

Comme une note, cela semble parfaitement juste idée pour moi, bien que j'ai observé que certaines personnes pensent que vous devez toujours spécifier de nouveau des commentaires dans la dérivée et de la mise en œuvre des classes. (En fait, j'ai fait moi-même dans la documentation de l'une de mes bibliothèques et je n'ai pas à voir les problèmes que ce soit.) Il y a presque toujours aucune raison pour que les commentaires diffèrent à tous, alors pourquoi ne pas hériter et de faire facilement?

Edit: au Sujet de votre mise à jour, de Châteaux de sable peuvent aussi prendre soin de cela pour vous. Château de sable peut sortir une version modifiée du fichier XML qu'il utilise pour l'entrée, ce qui signifie que vous pouvez distribuer cette version modifiée avec votre bibliothèque DLL à la place de celui qui est intégré directement par Visual Studio, ce qui signifie que vous avez les commentaires dans intellisense ainsi que le fichier de documentation (CHM, peu importe).
- Hey, c'est assez sympa! J'aime les Châteaux de sable!
- Message édité mis à jour pour répondre à la question.
- C'est un utile de modifier, merci!
- cela peut être fait sur un niveau de classe? de sorte que je n'ai pas à mettre des /// <inheritdoc /> avant chaque méthode.
- Une chose que j'ai remarqué, c'est que <inheritdoc/> n'a pas hérité de la documentation pour la <param> tag.
- Aller jusqu'à-voter cet utilisateur de la fonctionnalité vocale d'avoir <inheritdoc /> officiellement ajouté à la C# spec et de travailler avec VS intellisense visualstudio.uservoice.com/forums/121579-visual-studio/...
- Je ne suis pas sûr de ce que je fais mal, mais après la publication de mon package NuGet pour ma bibliothèque. Le <inheritdoc/> commentaires apparaissent en blanc. Est ce que quelqu'un d'autre rencontre ce?
InformationsquelleAutor Noldorin
11

Si vous ne l'utilisez pas déjà, je vous recommande vivement une version gratuite de Visual Studio addon appelé GhostDoc. Il facilite le processus de documentation. Jetez un oeil à mon commentaire sur un peu liés à la question.

Bien que GhostDoc ne sera pas à la synchronisation automatique, il peut vous aider à le scénario suivant:

Vous avez une documentation de la méthode de l'interface. Implémenter cette interface dans une classe, appuyez sur la GhostDoc touche de raccourci, Ctrl-Shift-D, et le commentaire XML à partir de l'interface sera ajouté à la méthode mise en œuvre.

Aller à la Options -> Clavier paramètres, et d'attribuer une touche à GhostDoc.AddIn.RebuildDocumentation (j'ai utilisé Ctrl-Shift-Alt-D).

Maintenant, si vous modifiez le commentaire XML sur le interface, appuyez sur cette touche de raccourci sur la mise en œuvre de la méthode et de la documentation sera mise à jour. Malheureusement, cela ne fonctionne pas vice-versa.
- La version la plus récente (5.3.16270) de GhostDoc pouvez également créer hérité docu. Je l'ai juste essayé pour mon implémentations d'interface. Joli bonus, il ajoute également des exceptions avec le message de l'exception 🙂
InformationsquelleAutor Igal Tabachnik
5

J'ai l'habitude d'écrire des commentaires de ce genre:
```
///<summary>
///Implements <see cref="IMyInterface.Foo(string, int)"/>
///</summary>
///<returns></returns>
```
Les méthodes sont utilisées uniquement par l'interface, donc ce commentaire n'est même pas affiché dans l'info-bulle lors du codage.

Edit:

Si vous voulez voir les docs lorsque vous appelez la classe directement et pas à l'aide de l'interface, vous devez l'écrire deux fois ou utiliser un outil comme GhostDoc.

InformationsquelleAutor Stefan Steinegger
4

Essayer GhostDoc! Il fonctionne pour moi 🙂

Edit: Maintenant que j'ai été mis au courant de Châteaux de sable de soutien pour <inheritdoc/>, j'approuve le Noldorin post. C'est une bien meilleure solution. Je continue de recommander GhostDoc sur une base générale, cependant.
- Personnellement je n'aime pas GhostDoc. Il permet de générer la documentation où il n'y a réellement aucun. C'est de cacher le fait que quelque chose n'est pas documentée. Juste un avis personnel, je ne dis pas que c'est quelque chose de mauvais en général.
- D'accord avec le commentaire de Stefan dans ce GhostDoc n'est pas parfait, mais il le fait passer automatiquement en "hérité" les commentaires de ce genre c'est donc une assez bonne réponse à la question.
- Stefan, je suis en désaccord sur le contraire, car GhostDoc uniquement le reflet de la documentation que vous avez déjà "mis" dans votre nom de membre (par la construction de la prose de l'noms), il ne génère que de la documentation où la documentation existe déjà (implicitement). En tant que tel, il "produit" rien, mais l'généré prose est un excellent point de départ pour lequel vous pouvez ajouter de la valeur réelle. Documentation réelle encore prend un peu de travail.
InformationsquelleAutor Tor Haugen
2

J'ai une meilleure solution: FiXml.

Le clonage est certainement l'approche de travail, mais il a des inconvénients, par exemple:
- Lorsque le commentaire d'origine est modifié (ce qui arrive souvent au cours du développement),
  son clone ne l'est pas.
- Vous êtes à la production énorme quantité de doublons. Si vous utilisez tout
  source outils d'analyse de code (par exemple, en Double Finder dans l'Équipe de la Ville), il sera
  trouver principalement vos commentaires.
Comme il a été mentionné, il n'est <inheritdoc> balise dans Château de sable, mais il a quelques inconvénients en comparaison à FiXml:
- De châteaux de sable produit des fichiers d'aide HTML compilés - normalement, il ne modifie pas
  .xml fichiers contenant des extraits des commentaires XML (enfin, ce ne peut pas être fait
  "à la volée" lors de la compilation).
- De châteaux de sable de la mise en œuvre est moins puissant. E. g. l'est pas
  <see ... copy="true" />.
Voir Sandcastle est <inheritdoc> description pour plus de détails.

Description courte de FiXml: c'est un post-processeur de documentation XML produit par C# \ Visual Basic .Net. Il est implémenté comme tâche MSBuild, il est donc très facile de l'intégrer à tout projet. Il aborde quelques ennuyeux cas lié à l'écriture de la documentation XML dans ces langues:
- Pas de support pour l'héritage de la documentation de base de la classe ou de l'interface. I. e. une documentation pour toute substituée membre doit être écrit à partir de zéro, bien que normalement, c'est tout à fait souhaitable d'hériter au moins la partie.
- Pas de soutien pour l'insertion d'couramment utilisé des modèles de documentation, telles que “Ce type est un singleton - utiliser ses <see cref="Instance" /> propriété pour obtenir la seule instance.”, ou même “Initialise une nouvelle instance de <CurrentType> classe”.
Pour résoudre les problèmes cités ci-dessus, le XML, les balises sont fournis:
- <inheritdoc />, <inherited /> tags
- <see cref="..." copy="..." /> attribut dans <see/> tag.
Ici est sa page web et page de téléchargement.
- Vous devez divulguer votre affiliation avec FiXml.
- Oui, c'est exact - je suis l'un de ses auteurs. Merci de m'aviser.
- Le lien est mort...
InformationsquelleAutor Alex Yakunin
1
```
///<inheritDoc/>
```
Lire ici

L'utilisation de ce

InformationsquelleAutor Krzysztof Kozmic
1

J'ai construit une bibliothèque de post-traiter les documents XML fichiers pour ajouter le support pour le <inheritdoc/> tag.

Alors qu'il ne l'aide pas avec Intellisense dans le code source, il ne permet pas de XML modifié les fichiers de documentation pour être inclus dans un package NuGet et fonctionne donc avec Intellisense référencés dans les packages NuGet.

Plus d'info à http://www.inheritdoc.io (version gratuite disponible).

InformationsquelleAutor K Johnson
0

Ne pas le faire. Pensez-y de cette façon - si les commentaires doivent être les mêmes tout le temps, puis l'un d'eux n'est pas nécessaire. Il y a une raison pour le commentaire (en plus d'une sorte de bizarre obligation de commenter-bloc de chaque fonction et de variable), de sorte que vous devez comprendre ce que l'unique raison est que.
- Je n'aurais pas utilisé l'interface, ici, n'avais-je pas été en faisant semblant de tests.
InformationsquelleAutor 1800 INFORMATION
0

Avec ReSharper, vous pouvez le copier, mais je ne pense pas que c'est la synchronisation de tous les temps.

InformationsquelleAutor crauscher

Vous devez vous connecter pour publier un commentaire.