标签: xml-documentation

• 我正在使用Code Contracts ver:1.4.40602.0
• 我复制了必要的内容和转换文件
• Sandcastle根据我的合同要求输出例外情况

示例代码:

public class MyClass
{
    public MyClass(Object obj)
    {
        Contract.Requires<ArgumentNullException>(obj != null);
    }
}

结果输出(在我的文档中):

| Exception                       | Condition                       |
|---------------------------------|---------------------------------|
| System.ArgumentNullException    | obj == null                     |

这并不是那么糟糕,但我想知道是否有办法自定义条件的文本？我试图添加用户消息Contract.Requires<ArgumentNullException>(obj != null, "obj is null.");,但这并没有解决任何问题.

在过去,我必须为异常编写自己的xml文档部分.我是否必须再次这样做以获得我需要的东西？

免责声明:由于Code Contracts(目前)是一个DevLabs项目,这可能会改变,但我想知道它现在是否已经可用......如果没有,我一定会建议它.

当类型名称足够重要时，属性名称默认为类型名称是相对常见的做法；

public class User { }
public class UserSession
{
    /// <summary>
    /// Creates a <see cref="UserSession" /> instance
    /// with the given <see cref="User" />
    /// </summary>
    public UserSession(User user)
    {
        User = user;
    }

    public User User { get; private set; }
}

我的问题是<see cref="User" />XML 文档中的元素引用了该UserSession.User属性。我应该写什么才能引用该User类型？

当提供相同方法的多个重载时,我经常不得不重复该方法的描述,这违反了DRY并增加了维护成本:

/// <summary>
/// Frobnicates all foos read from the given reader. Frobnication is a
/// process where ...[lots of text]...
/// </summary>
/// <param name="hasBar">[Description of hasBar]</param>
void FrobnicateFoo(TextReader reader, bool hasBar)
{
    ...
}

/// <summary>
/// Frobnicates all foos read from the given file. Frobnication is a
/// process where ...[same lots of text]...
/// </summary>
/// <param name="hasBar">[Same description of hasBar]</param>
void FrobnicateFoo(String path, bool hasBar)
{
    ...
}

如果重复具有相同目的的多个参数,则该问题变得更糟(作为示例给出"hasBar").

我找到的一个"解决方法"是"引用"其他文档:

/// <summary>
/// Frobnicates all …

与ValueTuple在C＃7，现在可以编写回归方法和属性或不明确声明类型消耗复合对象。然而，当没有提供文档时，这些命名元组可能会造成混淆。

由于记录库的主要并且可能是最方便的方法是使用 XML 文档，有没有什么方法可以使用 XML 文档来提供命名元组中变量的描述？

我知道显而易见的解决方案是声明一个类型并相应地记录它。但是，由于某些无法完成的“原因”，是否可以将 XML 文档中的数据成员记录在ValueTuple?

注： 类似的问题被问的来临之前ValueTuple。

如何在.Net中内联成员？让我解释.从注释中提取文档的大多数工具都支持某种内联文档,您可以在成员声明后添加简要说明.就像是:

public static string MyField; /// <summary>Information about MyField.</summary>

有没有办法在C#或.NET语言中执行此操作？

对于生成HTML文档的格式,JavaScript和处理器是否有任何注释文档格式？

目前我正在使用VSDoc xml注释在开发时提供IntelliSense帮助,但据我所知,没有文档生成器用于此类注释.所以,我的问题可能听起来像:是否有任何实用程序将VSDoc注释从JavaScript文件转换为HTML？

我正在使用VS-2010 Ultimate版本10.0.30319.1 RTMRel(来自关于框).

我编写了一个包含大量优秀XMLDOC(imho)的类库.由于我在各种解决方案中使用此库时不想进入的原因,项目本身不包括在内(如在右键单击解决方案中,添加现有项目..); 相反,我们只是添加对DLL的引用,就像它是第三方库一样.

在包含库的解决方案中,intellisense正常工作,我获得了XMLDOC的全部好处.不幸的是,那不是我将要使用它的地方!

在其他解决方案中,库只是一个引用的DLL,我得到intellisense,但没有XMLDOC.虽然我的图书馆基本上可以理解,但没有支撑轮,我想知道为什么会这样,以及我能做些什么呢.

非常可跳过的段落:我希望我脑子里那种相当愤世嫉俗的怀疑是我认为的那样毫无根据 - 也就是说,M $可能以某种方式"锁定"了这个功能,以便将它的访问权卖给第三方库开发人员...我想可以做一些事情,比如要求DLL由特定密钥签名,并提供一些在线付费服务,人们可以用这个密钥签署他们的DLL以启用功能,但考虑到它有多么宝贵拥有繁荣的第三方图书馆和组件开发人员的平台似乎不太可能有人打扰.

那么,有没有人有任何提示可以分享如何使这个工作？无论如何,每当我使用这个东西时,我都希望XMLDOC出现在intellisense中.:)

我正在使用NuGet GUI并尝试将XML文件与我的DLL一起包含,以便随DLL一起分发帮助.

当我在任何项目中安装包时,它成功添加了DLL引用,但是在添加了包的项目的bin文件夹中没有生成XML文件.

包文件\\ lib\.XML中提供了XML文件

任何帮助将非常感谢.

提前致谢

我在生成的WPF文件的XML文档中看到了两个摘要标记.一个来自预期的代码隐藏文件.另一个似乎是由编译器自动生成的,因为它似乎来自.g.cs文件.

知道如何删除第二个吗？

要重现(在VS2012中):

1. 从模板创建新的WPF应用程序.
2. 在Build的项目属性上,检查XML文档文件.
3. 建立.
4. 查看生成的WpfApplication1.xml文件.

我看到了这个:

<member name="T:WpfApplication1.App">
    <summary>
    Interaction logic for App.xaml
    </summary>
    <summary>
    App
    </summary>
</member>

这最终在Sandcastle生成的文档中如下:

App.xml App的交互逻辑

谢谢!

是否可以使用<summary>XMLDoc标签在Delphi中记录单位用途？怎么样？

我试过把摘要都放在unit：

/// <summary> Unit purpose: test </summary>
unit Test;

之后：

unit Test;
/// <summary> Unit purpose: test </summary>

两种方法都无济于事。将鼠标悬停在另一个单元中的单元名称上进行检查。同时，悬停适用于同一单位中的其他标识符