标签: xml-documentation

对于 methodA()，我想使用 /// xml 文档系统。我想记录一下 methodB() 应该在 methodA() 之前调用。

假设有人将methodB()重命名为renamedMethodB()，我希望注释中的旧methodB()引用更新为renamedMethodB()。假设有人删除了 methodB() （并且假设没有其他任何东西使用 methodB()），我希望程序不编译，或者至少生成一个警告，因为 methodB() 注释然后引用了一个不再存在的方法。

我确信我在某个地方看到过这样的例子，所以我认为这是可能的。我该怎么做？

我试图在 XML 文档注释中使用不同颜色的文本，如下图所示，“true”、“false”和“Window”一词的颜色为蓝色和绿色。

我尝试反编译包含这些内容的代码，但 xml 文档不同，并且 Microsoft 文档中也没有提及这种颜色。

使用时编译源代码时csc.exe,可以使用/ doc选项将源文件中的xml文档注释保存到外部xml文件中.

我想知道的是编译器为什么在该文件中包含我的代码的非公共成员的xml注释.由于我已经在源代码中有文档,因此在处理该项目时,我不需要xml文档文件中的任何内容.

如果我将dll用于另一个项目,我无论如何都不能使用非公共成员.那为什么它包含所有私人和内部成员的文档？

我还想知道是否有办法防止这种情况发生.

以下XML注释给出了编译时警告:

/// <summary>
/// Provides data for the <see cref="TextDraw.Click"/> event.
/// </summary>
public class TextDrawEventArgs : EventArgs
{
    //...

    public TextDraw TextDraw { get; private set; }
}

我希望TextDraw.Click引用TextDraw类中的事件,但它正在拾取TextDraw作为此TextDrawEventArgs类型的属性.

我该如何解决这个问题？

在 C# 源文件中编写 XML 文档注释时，是否需要替换"为"？这个问题讨论如何替换字符，但除了确定尖括号确实需要替换之外，没有确定哪些字符需要替换。

添加方法标题文档时，如何阻止StyleCop for Resharper（或ReSharper本身）在开始param元素标签之后和结束标签之前添加换行符。

从：-

/// <param name="name">
/// The name.
/// </param>

至：-

/// <param name="name">The name.</param>

我没有选中“ XML文档注释”部分下提到换行符的所有内容，但无济于事，但是找不到其他相关部分？

我一般在一个班级中宣称一个私人领域的土地以及一个从外面进入这个领域的公共财产(到目前为止没有什么壮观的笑容):

private bool doILookGood;

public bool DoILookGood
{
   get { return doILookGood; }
   set { doILookGood = value; }
}

现在我想知道是否有一种优雅而有效的方式来评论这种情况,而无需两次写同样的评论.换句话说,我希望保留IDE在使用工具提示进行鼠标悬停时向我显示变量注释的功能.

到目前为止,我正在以这种方式发表评论:

/// <summary>
/// This i always true.
/// </summary>
private bool doILookGood;

/// <summary>
/// This i always true.
/// </summary>
public bool DoILookGood
{
   get { return doILookGood; }
   set { doILookGood = value; }
}

我想要这样的东西:

/// <summary>
/// This i always true.
/// </summary>
private bool doILookGood;

/// <summary cref="doILookGood" />
public bool …

我已经开发了一个代码库,我花了很多时间将其记录下来.

使用三斜杠XML(xmldoc)注释来注释类,方法和属性.

/// <summary>
/// Adds two numbers together.
/// </summary>
/// <param name="a">The first number.</param>
/// <param name="b">The second number.</param>
/// <returns>The sum.</returns>
public int Add(int a, int b)
{
    return a + b;
}

但是当我将其编译成DLL文件并从我的其他项目引用它,或将其打包为我引用的NuGet包时,Visual Studio/IntelliSense不会为我的库提供任何文档.

为什么会这样,我该怎么办呢？

我有一个webapi项目,我正在利用swashbuckle框架来清除api文档.

我已按照指示使用我的控制器和DTO构建文档xml文件,并且它在本地运行良好.

但是,在生成swagger文档时,会引发500错误.我已经确认是否删除了我的xml注册行,生成了swagger doc并成功返回.

这是我的注册行:

GlobalConfiguration.Configuration.EnableSwagger(c =>
                    { 
...
    c.IncludeXmlComments($"{System.AppDomain.CurrentDomain.BaseDirectory}bin\\Company.MyApp.xml");
...

更新:我做了一些额外的日志记录,虽然IncludeXmlComments的这个lne在启动时成功运行,但当我从服务器请求swagger.json文件时,我得到一个System.IO.FileNotFoundException: Could not find file 'D:\home\site\wwwroot\bin\Monetary.Scheduling.xml'例外.当我使用Kudu工具查看这个目录时,我找不到这个文件.

TL; DR:为什么这个文件在本地显示正常,但是当我使用Kudu或Octopus nugget包部署到Azure时,这个文件不存在？

我们有一个 Asp.Net Core 2.0 Web 服务，我们将其部署在 Docker 容器中。

对于 Web 服务，我们生成一个 xml 文档文件，并在 Swagger-ui 中使用该文件。这适用于从项目本身生成的 xml 文档，但是当 Web 服务部署在 Docker 容器中时，我无法获得为可见的包含包生成的 xml 注释。

nuget 包（也由我们创建）确实包含一个 xml 文档文件，我们可以让 swagger 在本地机器上运行服务时使用它。通过调用 .IncludeXmlComments 使文档可用于 swagger，并且文档的路径是通过获取程序集的路径然后用 .xml 替换 .dll 扩展名来确定的。

我怀疑该包的xml doc文件未包含在容器中，因此无法找到。在 Dockerfile 我看到命令

COPY publish .

我想要一个还添加/复制包的 xml doc 文件的命令，或者知道如何使 xml doc 文件成为发布资产的一部分。任何其他能够以稳健的方式（不仅仅是在我的机器上）进行这项工作的解决方案也是受欢迎的。

编辑：我们现在在 Docker 容器中有额外的 xml doc 文件，但 Swagger 仍然没有显示该文件中提供的描述（它在本地运行时会显示）。我们使用了类似的东西：

<Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">  
    <ItemGroup>
        <DocFile Include="$(USERPROFILE)\.nuget\packages\{packagename}\**\lib\$(TargetFramework)\{PackageName}.xml" />
    </ItemGroup>
    <Copy SourceFiles="@(DocFile)" DestinationFolder="$(PublishDir)" SkipUnchangedFiles="false" />
</Target>

其中 {PackageName} 应替换为您的包的实际名称。路径中的通配符使其版本独立（尽管我们现在必须检查这是否会导致问题，因为我们有多个版本）。