我正在寻找C#的XML源代码文档的替代方案,该文档根据XML的本质介绍了很多噪声,这些噪声在眼睛上很重要并且需要编写更多工作:
/// <summary>
/// This is text of importance. Linking to
/// <see cref="AnotherClass>is somewhat verbose.</see>
/// </summary>
/// <param name="andSo">is parameter documentation</param>
相反,我想使用Markdown作为文档:
/// This is text of importance. Linking to [an](OtherClass) is less verbose.
///
/// Empty lines would make a new paragraph
///
/// aParameter
/// : could possibly be documented in definition-list manner
/// as in http://bit.ly/1l9ik26
我敢打赌我之前在Stackoverflow上找到了一个问题和答案.不幸的是我不能再找到它了.我尝试了所有可以想象的搜索关键字变体而没有运气.所以我希望你们中的任何人都能找到副本.至少我的问题将通过为现有问答提供不同措辞的"代理"来增加一些价值,从而提高未来访问者查找信息的几率.
更新:
我想我终于通过使用不同的搜索引擎找到了另一个问题:Markdown用于自动生成doc？.似乎Doxygen支持Markdown.Doxygen也支持C#.但对于@Sam Harwell提到的要求,这可能不会有很长的路要走.
我总是使用C#xml语法为类和方法编写好的代码注释.我一直希望以后能够轻松地将它们导出.
今天我实际上必须这样做,但我很难找到方法.有什么我想念的吗？我想去菜单 - >构建 - >构建代码文档,但没有选项可以做到这一点.
我在VS 2012中使用C#,在我的代码中添加了XML文档,并且我不小心打开了StyleCop规则(特别是SA1609),它"验证了public或protected属性包含带有值标记的文档头".
还有另一条规则(SA1604,此次故意启用),"验证文档标题包含格式正确的摘要标记".
但是,我很难看到你放在摘要标签中尚未包含的值标签中的内容.目前我的摘要标签说的是"获取或设置某些东西".应该在相应的值标签中添加什么来补充它？
(只是为了澄清,我很高兴设置StyleCop - 它只是在我意外打开所有文档规则时引起了我对值标记的注意)
MSDN对这个问题的帮助不大:
在XML文档中为属性提供摘要和值标记有什么意义？如何在不重复自己的情况下使用它们？
使用XML文档文件附带的外部程序集时,如何让visual studio找到它？
有XML文档文件时,是否有一个程序或xml转换文件或者我可以用来以一种很好的方式查看它的东西？不一定像msdn文档查看器那样复杂,但至少比纯xml更好...
我想记录枚举类型字段的默认值:
/// <summary>
/// The default value is <see cref="Orientation.Horizontal" />.
/// </summary>
public Orientation BoxOrientation;
编译器警告它无法解析引用.前缀F:或M:使编译器静音,但E:也可以,所以我不确定哪个前缀是正确的.
有
///<summary>
///This is summary for some class or method
///</summary>
类或方法的文档.但是如何为简单的变量或列表编写这个？
我使用Visual Studio 2010,当我将鼠标悬停在某个列表,属性或者我希望看到的某种摘要(在那个小工具提示中)时,我已经写了那个特定的东西.
///<doc>
///always use this list!
List<String> beer = new List<String>();
编辑:好的,我们已经发现,它像往常一样在你的班级中发表评论,但是OUTSIDE方法或功能!!
有什么办法在方法中记录/评论吗？
public class BeerForall
{
/// <summary>
/// it works here
/// </summary>
public List<String> beer = new List<string>();
public String giveBeer()
{
/// is not working, u can not comment
/// <summary>
/// test test, not working
/// </summary>
List<String> moreBeer = new List<string>();
return "beer";
}
}
我正在使用xml注释来记录我的组件的公共以及内部和私有成员.我想将生成的文档xml文件与组件程序集打包在一起,以便为最终产品启用"丰富"(例如,使用方法,异常和参数描述)Visual Studio Intellisense.它的问题是C#编译器为所有内容(包括内部类,方法,内部枚举的私有字段等)创建文档条目,并且似乎没有切换到"仅公共成员"模式.
现在我不想在每个文件中使用XX方法查看超过50个文件,并删除私人和内部成员的所有注释.即使我这样做,我可能也不会在auto-gen'd资源文件上取得太大成功,因为这些强类型资源类会自动注释而非公开.
我的问题是:是否有一些选项/标志我忽略了？如果不是,是否有一些工具可以帮助将公共成员与其他成员分开(在我开始编写代码之前)？
我的visual studio解决方案包括Web应用程序和单元测试应用程序.我的Web应用程序使用log4net.我希望能够从命令行使用msbuild来构建我的解决方案.但是,每当我从命令行构建解决方案时,我都会遇到构建错误,因为它无法将log4net.xml复制到测试项目的bin目录中.
错误消息是:
"无法将文件'\ bin\log4net.xml'复制到'bin\Debug\log4net.xml'.拒绝访问路径'\ bin\log4net.xml'."
看起来Visual Studio正在锁定此文件,但我无法弄清楚它为什么需要.有没有办法阻止VS在已加载的项目中锁定XML文档文件？
我有一个具有多个目标的库项目,例如它在CSPROJ文件中:
<TargetFrameworks>net40;net46;net461;net462;net47</TargetFrameworks>
如果我想为这些目标框架和所有组合的XML文档Debug和Release配置,我使用生成配置管理器来选择每一个设置在用户界面,然后将其设置为建立该组合XML文档和每一个组合,然后单独作为上市a PropertyGroup在CSPROJ中,带有XML文档的预期输出文件.
有没有更好的办法？
发布问题和答案,因为我没有在网上找到其他任何记录