XML Documentation Commentaires avec des interfaces et de la classe d'exécution (es) [fermé]

Question

Je suis un ensemble à l'aide documente Documentation Commentaires , dont un fichier CHM sera créée en utilisant Sandcastle .

Mon assemblage contient différentes interfaces, dont chacun est mis en œuvre par une classe (dans mon scénario ce sont les services WCF).

J'ai ajouté la documentation aux interfaces, est-il possible pour moi au document automatiquement les méthodes pertinentes sur les classes de mise en œuvre?

Answer 1

Il semble ne pas être un soutien pour un tel autodocumentation dans Sandcastle. Sandcastle Aide File Builder implémente bien une balise inheritdoc personnalisée.

A partir du site SHFB:

  

Le support est inclus pour la    balise qui vous permet de   hériter la documentation de la base   types / membres. Ceci est mis en œuvre par l'intermédiaire   un outil autonome il peut aussi être   utilisé par d'autres outils tiers et   créer des scripts. Cet outil fournit   caractéristiques au-delà de ceux qu'on trouve dans la   construire composant fourni avec   Sandcastle.

Deuxième mise à jour: selon ce workitem , le Sandcastle "support" pour inheritdoc est à travers l'outil SHFB. En bout de ligne, je suppose est, SHFB résout votre problème.

Answer 2

J'ai une meilleure réponse. FIXML

commentaires clonage avec GhostDoc \ AtomineerUtils est certainement approche fonctionne, mais il présente des inconvénients importants, par exemple .:

• Lorsque le commentaire original est modifié (ce qui arrive souvent au cours du développement), son clone n'est pas.
• Vous produisez énorme quantité de doublons. Si vous utilisez une outils d'analyse de code source (par exemple Duplicate Finder dans la ville de l'équipe), il trouver principalement vos commentaires.

Comme il a été mentionné, il y a balise <inheritdoc> Sandcastle , mais il a quelques inconvénients par rapport à FIXML:

• Sandcastle produit compilé les fichiers d'aide HTML - il ne modifie pas les fichiers .xml contenant des commentaires XML extraits. Mais ces fichiers sont utilisés par de nombreux outils, y compris .NET réflecteur et navigateur de classe \ IntelliSense dans Visual Studio .NET. Donc, si vous utilisez juste Sandcastle, vous ne pourrez pas y voir la documentation héritée.
• La mise en œuvre de Sandcastle est moins puissant. Par exemple. l'est pas <see ... copy="true" />.

Voir Description <inheritdoc> de Sandcastle plus de détails.

Description succincte du FIXML: il est un post-processeur de documentation XML produit par C # \ Visual Basic .Net. Il est mis en œuvre comme tâche MSBuild, il est donc assez facile de l'intégrer à tout projet. Il aborde quelques cas gênants liés à la documentation XML écrit dans ces langues:

• Pas de support pour la documentation héritant de la classe de base ou de l'interface. à savoir une documentation pour tout membre surchargée doit être écrit à partir de zéro, bien que normalement il est tout à fait souhaitable d'hériter au moins la partie.
• Pas de support pour l'insertion de modèles de documents couramment utilisés , comme « Ce type est singleton -. Utiliser sa propriété <see cref="Instance" /> pour obtenir le seul exemple de celui-ci », ou même « Initialise une nouvelle instance de classe <CurrentType>. »

Pour résoudre les problèmes mentionnés, les balises XML supplémentaires suivantes sont fournies:

• balises <inheritdoc />, <inherited />
• attribut <see cref="..." copy="..." /> dans la balise <see/>.

Voici sa page Web et page de téléchargement .

Answer 3

Un outil tel que GhostDoc peut générer la documentation sur les cours d'exécution, lorsque vous utiliser le raccourci clavier de lui. Ce n'est pas tout à fait automatique, mais pourrait aider à prévenir trop coller copie.

On pourrait peut-être automized avec un script.

Answer 4

AtomineerUtils vont générer automatiquement des commentaires pour vous, et il ramasse la documentation existante et de la classe de surcharge de base surchargée, vous permettant d'économiser des charges de tracas à dupliquer les informations où il est nécessaire.

http://www.atomineer.com/AtomineerUtils.html