Utilisation d’atsortingbuts pour la documentation en C #

Dans le didacticiel d’atsortingbuts MSDN, ils utilisent Author comme exemple d’atsortingbut:

 [Author("Jane Programmer", Version = 2), IsTested()] class Order { // add stuff here ... }

Cela me semblait être une bonne idée car cela vous permettrait d’utiliser la reflection pour regrouper les classes par auteur (par exemple) – exposant efficacement les métadonnées qui seraient normalement dans la documentation du compilateur, ce qui pourrait être utile. J’ai immédiatement pensé “aha! Je devrais utiliser des atsortingbuts pour toute la documentation de mon bloc en ligne” – par exemple:

 [Author("Me")] [Description("Add 1 to value")] [Param("value", "The original value to add 1 to")] public int AddOne(value) {return value + 1;}

Cependant, aucune des réponses que j’ai pu trouver sur la documentation et les atsortingbuts ne semble suggérer cette méthode. Ils utilisent tous XML pour la documentation en ligne.

Existe-t-il des atsortingbuts intégrés pour aider à la documentation en ligne? Sinon, existe-t-il des bibliothèques / packages qui incluent des ensembles d’atsortingbuts prédéfinis pour la documentation en ligne ?

Certains inconvénients de la conservation de la documentation dans les atsortingbuts:

mauvaise mise en forme pour les textes longs;
aucune prise en charge par les add-ons Visual Studio (par exemple, utilisation de la fonction de prévisualisation de la documentation de ReSharper);
pas de support par des outils tiers de génération de documentation;
l’inclusion de la documentation dans les assemblages, ce qui facilite considérablement l’ingénierie inverse;
la duplication des métadonnées dans les codes source avec les métadonnées stockées dans un système de contrôle de version (il est inutile de suivre l’auteur et la version de la déclaration dans le code source, lorsque le VCS vous donne des informations beaucoup plus précises – les VCS ne mentent pas ).

Je ne vois aucun avantage pour le moment. Au cas où j’en aurais vraiment besoin, il est toujours possible d’parsingr les commentaires de la documentation XML et de transformer l’ensemble de la base de code en n’importe quelle forme atsortingbuée.

La question ici semble être “qu’est-ce que la documentation?”. Si le «matériel» qui vous intéresse doit être accessible par reflection, votre solution implicite d’atsortingbuts est une solution. Mais si l’intention est d’utiliser des outils de documentation standard pour construire la documentation, il en va tout autrement.

La nécessité ici appelle la solution. Quelle est la nécessité de la “documentation”. Peut-être la mauvaise question?

Par souci de complétude, dans les projets de test, vous pouvez effectuer les tâches suivantes:

 [TestProperty(“Author”, “Ducky”)] public void SomeTest() { ... }

Vous pouvez étendre cette approche au code normal. Je préfère ne pas commenter sur des questions théoriques. Cela dit, un script utilisant le référentiel pour extraire tous les “auteurs” / “éditeurs” du fichier / de la classe / de la méthode spécifique peut être créé.