Question

我爱XML comments。然而，随着一切崩溃，每两行看起来像：

[/// summary ...]
public void CreateUser(string username, string password)[...]

将此数字乘以数十或数百种方法，并且生成的折叠代码很难筛选出来。 我可以将这些评论移到单独的XML文件，并且仍然让Visual Studio识别该关联，以便它们仍然显示在Intellisense中吗？如果是这样，我该如何建立这种关联？我还使用SandCastle根据这些注释生成文档，因此SandCastle也必须识别该关联。

Answer 1

您可以使用<include file='...' path='...'>标记来引用外部评论。请参阅http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx。

我不知道有任何工具可以将现有源文件中的注释移动到外部注释文件中。

Answer 2

我可能要晚7年了，但是我想这样做，所以我找到了一种将所有文档以一种XML格式存储的方法，但是您可能必须手动完成其余操作，然后将其添加到.csproj文件中以下：

  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

在构建项目时，您将在输出目录中找到一个<ProjectName>.xml文件，其中将包含所有内联文档，您可以复制该文件的内容（您可能有在xml中编辑一些标签，但可能不会太多），并将其放置在项目中的文件中。

然后，您可以使用<include>标签替换现有文档。

Answer 3

答案简短：AFAIK编号

XML注释对于第三方将使用的公开方法非常有用。由于我添加到应用程序中的几乎所有面向公众的功能都是通过合同接口完成的（帮助测试能力）我会根据接口声明放置注释，只使用＆lt; see cref =“...”/＆gt;在实施之上。

接口：

///<summary>
/// Provides so-in-so fetching functionality on the provided criteria.
/// Examples, parameters, etc.
///</summary>
IEnumarable<Something> FetchSomethingsBaseOnCriteria(params Criteria[] criteria);

实施

///<summary>
/// <see cref="ISomethingDoer.FetchSomethingsBasedOnCriteria"/>
///</summary>
IEnumarable<Something> ISomethingDoer.FetchSomethingsBaseOnCriteria(params Criteria[] criteria)
{
  // Get fetching...
}

不确定大多数文档生成器是否具有解析来自＆lt; see /＆gt;的注释的智能我相信Sandcastle有＆lt; Inheritdoc /＆gt;标签，它将允许它采取基本接口的注释。 http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

如果使用多态接口，这可能无效。（我认为你不能覆盖中间接口中的声明/评论）

对于内部使用和私有代码，我不打扰评论，因为它是额外的开销，经常解释显而易见的。它们太容易让人失去同步，在这种情况下，他们开始误导用户或需要被忽略。（“评论谎言。” - 清洁代码）我依靠BDD风格的单元测试来描述我打算执行的代码，以及用于描述自身的描述性代码。

将XML注释移动到单独的文件中

3 个答案: