在 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 ...
}
这在我看来是个好主意,因为这将让你按作者(例如)使用反射来群类 - 有效地揭露元数据通常会在文件编译器,这可能是有用的。我马上想到啊哈,我应该使用属性为我所有的内联块文档! - 例如:
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;}
但无of the answers我能找到的有关文档和属性似乎表明这种方法。它们都使用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.
是否有任何内置属性,以协助内联文档?如果不是,是否有任何库/包在那里包含 pre-定义的属性集在线文档
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:
较差格式的长文; 由Visual Studio不支持插件(例如,使用ReSharper的文档preVIEW功能); 由第三方文档生成工具不支持; 包含文件的组件组成显著简化逆向工程; 在元数据源$ C $ CS存储在一个版本控制系统元数据的重复(有追踪任何声明的作者和版本源$ C $ C,当VCS给你更多的precise没有意义信息 - 的 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文档的意见和改造整个codeBase的成任何形式的原因。
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.