标签: xml-comments

当我在Visual Studio中按///时,是否可以从此更改生成的代码段:

/// <summary>
/// 
/// </summary>

对此？:

/// <summary></summary>

我在一个团队中工作,我们在StyleCop中使用了广泛的规则集,我想知道关于这样一个工具停止有用并且开始变得烦人的一般观点的想法.我们还使用GhostDoc,因此代码中充斥着XML注释,这使得代码更难以阅读并因此进行审查.我对XML注释没有任何问题,并且发现它们在某些地方非常有用,但它们是否真的需要在每个字段和属性上？

我们有一个令人钦佩的目标:"每个项目在构建时必须有0个警告"但当然这个目标需要违背合理的StyleCop规则集,否则会浪费宝贵的时间来"修复"StyleCop警告的原因.

有什么想法？

编辑 我现在真的想知道什么是像ALL ALL的stylecop工具的论据？为什么不放弃它,让合理的编码标准和良好的代码审查来处理其余的事情？特别是在一支优秀的团队中？当然,获得0警告的任务实际上会增加价值,因为所有警告都是相关的.

我认为GhostDoc的唯一优势是它可以为您从头开始编写XML注释节省大量时间.我不认为你应该接受生成的评论而不进行编辑 - 这可能适得其反.

这是由GhostDoc生成的xml注释满足的Stylecop规则(SA1642:ConstructorSummaryDocumentationMustBeginWithStandardText)的组合 - 是否在一天结束时添加任何值？

    /// <summary>
    /// Initializes a new instance of the <see cref="SomeCustomType"/> class.
    /// </summary>
    /// <param name="someParameter">The someParameter.</param>
    public SomeCustomType(string someParameter)
    {
    }

是否有一种标准方法,用于生成API文档的工具处理部分类的XML样式注释？基本上,应该如何评论部分类/方法,以便生成的帮助文档不被破坏？这个问题可能因使用的工具而异,在这种情况下,我想最重要的两个工具是:

• Visual Studio的内置方法来创建XML文档
• 微软的Sandcastle

我不希望我的XML文档出来时髦

/// <summary>Some Foo class</summary>
public partial class Foo { ... }

/// <summary>Some Foo class that implements some interface.</summary>
public partial class Foo : ISomeInterface { ... }

这真的只是重新询问有关Visual Studio 2008的问题.VS2010是否提供任何功能来摆脱自动生成代码的CS1591编译器警告？

CS1591: Missing XML comment for publicly visible type or member

引用VS2008的问题:

这不仅仅是一个问题,而是一个烦恼.我的项目包含许多自动生成的文件(使用mgmtclassgen.exe).当我生成XML文档时,我精美评论的库受到来自这些autogen文件的xml文档警告的困扰.

有没有办法a)抑制生成这些文件的文档或b)抑制警告CS1591只是为了一组文件？我显然不想修改自动生成的文件,即使只是添加抑制编译指示.

编辑:在我的情况下,违规文件由WCF RIA服务生成,因此生成错误的文件是自动生成的WebContext类(MyProject.BusinessApplication.Web.g.cs).

我无法手动修改此文件,因为它是动态生成的,所有更改都将被删除.我也不想全局禁用警告,因为它对我的非自动生成的代码很有帮助.

好吧,这是一个愚蠢的问题,但是当使用Visual Studio时,如果我在Visual Basic中编写XML文档注释,我可以使用tab键在字段之间切换(例如,摘要到Param到返回).但是,在C#中,按Tab键会插入一个Tab,所以我必须单击各个字段才能导航到它们(或使用箭头键).这使本来应该是一个简单而繁琐且耗时的过程.

有人知道我是否可以使用默认键盘快捷键,或者如果有特定命令我可以映射到未使用的键盘快捷键？我正在使用带有ReSharper 6.1的Visual Studio 2010.在SO档案中进行了一些搜索,但是没有其他人有这个问题,或者我不知道要问的正确关键字(后者更有可能).提前致谢!

编辑:我应该澄清一下.VB中的Tab键行为是Visual Studio 2010的原生行为; ReSharper安装是相当新的(在我切换到C#之后),我想提一下,以防有人知道ReSharper是否为此增加了他们自己的导航快捷方式(因为他们有吨).再次感谢!

有没有一种从Visual Studio XML输出生成MSDN样式文档的简单方法？
我没有耐心为它建立一个好的xslt,因为我知道我不是第一个跨过这座桥的人.

此外,我最近尝试设置沙堡,但它真的让我的眼睛交叉.要么我错过了一些重要的过程,要么就是太过牵扯.

我知道那里的人有一个非常好的简单解决方案.

我在这里重申,因为我认为我的格式化使该段非邀请阅读:

我尝试了一下沙堡,但很难设置它.我真正想到的是更简单的事情.

也就是说,除非我不理解沙堡过程.对我来说,为了给测试人员提供一些好的东西,这似乎是一件非常多的额外包袱.

我想在web.config文件中添加注释,如下所示:

<httpRuntime 
  requestValidationMode="2.0"      // require for [ValidateInput(false)] in .net-4.0
  requestPathInvalidCharacters=""  // include & character in the url
  enableVersionHeader="false"      // disable X-AspNet-Version header
  />

有没有办法以这种方式发表评论,使用服务器端评论<% %>或类似的东西？

早上好,下午好,晚上好或晚上好(取决于你的时区).

这只是关于C#中XML注释的一般问题.我从来没有对评论我的程序做过很大的贡献,我一直都是一个冗长的变量/属性/方法名称,让代码说明一切.如果我编写的内容相当令人困惑,我会写评论,但在大多数情况下,我不会写很多评论.

我正在阅读有关.NET,Sandcastle和codeplex上的帮助文件构建器中的XML注释的文章,它让我想要记录我的代码并为那些必须深入研究我的人生成一些很好的,有用的文档.代码,当我不在这里.

我的问题是关于标准和惯例.是否有"好"XML评论指南？你应该评论每个变量和属性吗？每个方法？我只是在寻找有关如何编写好的注释的提示,这些注释将由sandcastle编译成良好的文档,以便其他程序员在最终不得不处理我的代码时不会诅咒我的名字.

提前感谢您的意见和建议,Scott Vercuski

在C#中,我试图使用<see cref ="blah"/>来引用包含params关键字的方法签名.我知道这会将参数列表转换为数组,但我甚至无法弄清楚如何在CREF属性中引用数组.我在搜索中找不到任何内容,也不知道我知道的任何人.编译器在方括号上窒息.我已经尝试了各种不同的组合,使用花括号,使用Array类,但没有任何工作.有谁知道这个？

我正在尝试在VB.Net中的XML注释中添加换行符.我读过另外两篇关于C#的帖子,

C#中的XML多行注释 - 我做错了什么？

为Intellisense的注释添加换行符

但建议<para>或<br/>标签不起作用.这个,

    ''' <summary>
    ''' <para>Line one</para><br />
    ''' <para>Line two</para><br />
    ''' </summary>
    ''' <value></value>
    ''' <returns></returns>
    ''' <remarks></remarks>
    Public Property Speed As Double

仍然看起来像这样:

我怎样才能做到这一点？