使用属性在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 ...
}

这在我看来是个好主意，因为这将让你按作者（例如）使用反射来群类 - 有效地揭露元数据通常会在文件编译器，这可能是有用的。我马上想到啊哈，我应该使用属性为我所有的内联块文档！ - 例如：

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;}

但无<一href="http://stackoverflow.com/questions/12554721/attributes-and-xml-documentation-for-method-property">of <一href="http://stackoverflow.com/questions/9423795/documenting-authorize-attribute-usage-producing-a-report">the <一href="http://stackoverflow.com/questions/7157277/using-c-sharp-attributes-and-documentation">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.

这篇关于使用属性在C＃中的文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！