在C＃中使用文档的属性 [英] Using Attributes for Documentation in C#
问题描述
在 MSDN属性教程他们使用作者作为一个属性的例子：
In the MSDN Attributes Tutorial they use Author as an example for an attribute:
[Author("Jane Programmer", Version = 2), IsTested()]
class Order
{
// add stuff here ...
}
这似乎是一个好主意，因为它将允许您使用反射将作者分组（例如） - 有效地将通常在文档中的元数据暴露给编译器，这可能是有用的。我立即想到aha！我应该使用所有内嵌块文档的属性 - 例如：
This seemed to me to be a good idea because it would allow you to use reflection to group classes by author (for example) - effectively exposing metadata that would normally be in documentation to the compiler, which could be useful. I immediately thought "aha! I should be using attributes for all my inline block documentation" - e.g.:
[Author("Me")]
[Description("Add 1 to value")]
[Param("value", "The original value to add 1 to")]
public int AddOne(value) {return value + 1;}
但是没有 答案我可以找到关于文档和属性似乎建议这种方法。他们都使用XML进行内联文档。
However none of the answers I could find about documentation and attributes seem to suggest this method. They all use XML for inline documentation.
是否有任何内置属性来协助内联文档？如果没有，是否有任何库/包，包括预定义的内联文档属性集？
Are there any built-in attributes to assist with inline documentation? If not, are there any libraries / packages out there that include pre-defined sets of attributes for inline documentation?
推荐答案
将文档保存在属性中的一些缺点：
Some disadvantages of keeping documentation in attributes:
- li>
- 不支持Visual Studio插件（例如使用ReSharper的文档预览功能）;
- 不支持第三方文档生成工具;
- 在程序集中包含大量简化逆向工程的文档;
- 使用版本控制系统中存储的元数据在源代码中复制元数据（没有任何意义可以跟踪任何声明的作者和版本在源代码中，当VCS为您提供更准确的信息时 - VCS不要谎言）。
- poor formatting for long texts;
- no support by Visual Studio add-ons (e.g. using ReSharper's documentation preview feature);
- no support by 3rd party documentation generation tools;
- inclusion of documentation in assemblies which significantly eases reverse engineering;
- duplication of metadata in source codes with metadata stored in a version control system (there's no point in tracking any declaration's author and version in the source code, when the VCS gives you much more precise information — VCS's don't lie).
我现在不能想到任何优势。如果我真的需要它，总是可以解析XML文档注释，并将整个代码转换成任何归属的形式。
I can't think of any advantage right now. In case I would really need it, it's always possible to parse the XML documentation comments and transform the whole codebase into any attributed form.
这篇关于在C＃中使用文档的属性的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
