标签: xml-comments

我目前正在记录我的 C# 代码，并发现包含一个直接显示应如何调用一段代码的代码块很有用。我使用<code>嵌入到摘要中的标签：

虽然这通常有效，但我想保留空白（换行符、缩进）。到目前为止我尝试了以下操作：

• 我将该xml:space="preserve"属性应用于<code>标签，但这根本没有效果。
• 我曾经<br />指示单独的新行（这在 VS 2019 中有效），但我无法插入空格或制表符。我尝试使用 （用于空格）和	（用于选项卡），但弹出窗口不会显示这些。
• 我尝试使用一个CDATA部分，但之间的代码根本没有显示。

有什么方法可以保留 C# XML 注释的代码标签中的空白吗？提前谢谢你的帮助。

当我在Visual Studio中键入触发器自动注释功能时(通过键入"'''"或"///"),大多数XML注释细节都会显示我喜欢的内容.但是,我通常会将历史记录标记添加到文档中,以便跟踪和更改随时间推移的方法.

有没有什么办法可以自定义自动评论功能,以便它添加历史记录标签,并可能添加一些通用名称 - 日期 - 更改占位符文本？

在下面的例子中,&并且Δ可以但Δ不是(后两者都是Δ).编译器发出类似于的警告:

warning CS1570: XML comment on 'XXX.DocumentedMethod()' has badly formed XML -- 'Reference to undefined entity 'Delta'.'

    /// <summary>
    ///  &amp; &Delta; &#916;
    /// </summary>
    public void DocumentedMethod()
    {

    }

XML注释支持的字符实体有哪些？

记录类和接口的最佳实践是什么？假设您有一个名为Foo的具体类,它派生自一个名为IFoo的接口.你在哪里提出你的方法评论？您是否在界面以及具体类上复制了您的注释？

以下是注释重复的示例:

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}

我无法理解使用XML注释的优点.我知道它们可以转换成代码外部的漂亮文档,但使用更简洁的DOxygen语法可以实现相同的目标.在我看来,XML注释是错误的,因为:

1. 它们总体上混淆了评论和代码.(它们更难以被人类阅读).
2. 可以在单个屏幕上查看更少的代码,因为"summary"和"/ summary"需要额外的行.
3. (已删除)

那可能是什么原因,为什么XML在.NET中更受欢迎而不是简单的DOxygen语法？

我有这样的XML评论.

/// <summary>
/// Lorem ipsum
/// </summary>
/// <param name="entity"></param>
/// <returns></returns>

我想在其中放置一条(多行)代码.我怎样才能做到这一点 ？

编辑

以下是有关多行代码的信息为Intellisense的注释添加换行符

在C#中使用XML注释,我可以记录一个方法可能抛出异常:

<exception cref="FooException">Thrown if foo is invalid.</exception>

但是,如果某个方法exception的XML文档中没有标记,则这可能意味着以下两种情况之一:

1. 作者彻底测试了该方法,确保它永远不会抛出异常,并希望通过不添加exception标记来记录这一事实.
2. 作者并不关心记录异常,因此这种方法可能会抛出任何东西.

根据我的经验,第二种情况通常就是这样.那么问题是:

如何明确记录方法永远不会抛出异常？

到目前为止,我提出的最好的方法是简单地在方法中提及它summary,例如"此方法不会抛出异常".但我想知道是否有更正式的方式表达这一点,就像throw()在C++中一样(尽管这可能是一个不好的例子).

当询问 C# 代码中文档注释的约定时，答案总是导致使用 XML 注释。Microsoft 本身也推荐这种方法。https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

/// <summary>
/// This is an XML comment.
/// </summary>
void Foo();

但是，在检查 Microsoft 的代码（例如 ASP.NET Core）时，注释看起来像这样。

//
// Summary:
//     A builder for Microsoft.AspNetCore.Hosting.IWebHost.
public interface IWebHostBuilder

包含的文档生成工具是否符合此约定，或者是否有使用此约定而不是 XML 的文档生成工具？为什么微软在他们的代码中使用这个约定而不是他们自己推荐的 XML 注释？

我们有一个 C# 项目，由于历史原因，该项目在同一代码中同时使用 Doxygen 和 Visual Studio 风格的注释。有没有人尝试过系统地将一种标准转换为另一种标准，最好转换为公共 XML 子集？

我想编写一个脚本来涵盖最常见的功能不会太困难，但我不想重新发明轮子。

是否可以为对象浏览器(VS 2010)中的set和get asssessors添加xml-comments？

        /// <summary>
        ///   Something abot property.
        /// </summary>

        public bool IsSomething
        {
              // get description

              get
              {
                    return isSomething;
              }

              // set description

              set
              {
                    // do some work
              }
        }