5

我喜欢XML 注释。然而，随着一切都崩溃，每两行看起来像：

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

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

4

3 回答 3

7

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

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

于 2012-07-18T03:43:40.533 回答
2

我可能晚了 7 年，但我想做同样的事情，我找到了一种方法来获取一个 XML 中的所有文档，但您可能必须手动完成其余的工作，将.csproj以下内容添加到文件中：

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

当你构建你的项目时，你会在输出目录中找到一个<ProjectName>.xml包含所有内联文档的文件，你可以复制这个文件的内容（你可能需要在 xml 中编辑一些标签，但可能不多)并将它们放在项目中的文件中。

<include>然后你可以用标签替换现有的文档。

于 2019-09-18T13:21:40.023 回答
0

简短的回答：AFAIK 没有。

XML 注释对于第三方将使用的公开公开的方法很有用。由于我添加到应用程序中的几乎所有面向公众的功能都是通过契约接口完成的，（有助于测试能力）我将把注释放在接口声明上，并在上面使用 <see cref="..."/>执行。

界面：

///<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...
}

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

在您使用多态接口的地方，这可能不起作用。（我认为您不能在中间接口中覆盖声明/注释）

对于内部使用和私有代码，我不理会注释，因为它通常是解释显而易见的额外开销。它们太容易失去同步，在这种情况下它们开始误导用户或需要被忽略。（“评论的谎言。”——干净的代码）我依靠 BDD 风格的单元测试来描述我打算用代码做什么，并用描述性代码来描述自己。

于 2012-07-18T03:05:11.340 回答