标签: xml-documentation

可能重复:
如何在xml文档中引用泛型类和方法

我一直在使用see cref标签,它工作得很好,但现在我需要在see cref中包含一个string []的通用列表,但是文档没有正确呈现.

    /// <returns>A <see cref="List<string[]>" /> that .......

我认为它与<和>有关,也许[]

这是允许的,有解决方法吗？

我想知道这些XML引用是如何工作的,我只是不知道它们为什么工作或为什么它们不起作用而我没有发现任何相关信息.

这是一个例子:

type
  TOuterClass= class
  strict private
    type
      TLogger = class
      public
        /// <summary>adds a log entry</summary>
        /// <param name="Msg">text to log</param>
        procedure Log(const Msg: string);
      end;
  strict private
    FLogger: TLogger;
  public
    /// <summary>adds a log entry</summary>
    /// <param name="Msg">text to log</param>
    /// <remarks>just calls <see cref="TOuterClass.TLogger.Log" />
    /// </remarks>
    procedure Log(const Msg: string);

    property Logger: TLogger read FLogger;
  end;

TOuterClass.Log注释中的链接不起作用.Delphi XE5只是考虑它然后放弃了.

另一个很简单的例子:

Unit MyUnit

type
  /// <summary>MyType Comment</summary>
  TMyType = reference to procedure;

/// <param name="MyTypeParam"><see cref="MyUnit.TMyType" /></param>
procedure …

编辑:已更新,指定仅在打包Azure云服务CSPKG文件时才会出现此问题.

我有一个ASP.NET Web API 2应用程序,它充当Azure云服务解决方案中的Web角色.我想使用Web API帮助页面并利用XML生成的文档来填充它们.我无法弄清楚如何将XML文档包含在Web Api项目的Azure云包中.

XML文档在本地正确地进入bin目录,并且在发布到文件系统位置时,但在检查cspkg存档或已部署的Web角色approot目录时,它会丢失.

有没有办法强制打包包含XML？

我正在使用xsd.exe从xsd文件集合生成C#类.xsd文件使用<xsd:documentation>标记来包含有用的描述.例:

<xsd:complexType name="AddressType">
    <xsd:annotation>
        <xsd:documentation>A formatted or free form address and its intended use.</xsd:documentation>
    </xsd:annotation>

不幸的是,所有这些都在生成的C#类中丢失了.有趣的是,每个类都附有一个空的备注文档标记.

/// <remarks/>

如何在生成的C#类中包含此文档(在文档标签中)？

我到处都读过doxygen是为C#代码生成文档的方法.我有一个我想要首先记录的界面(婴儿步骤),它已经有XML注释(///).

由于有大量的帖子和信息(包括doxygen.org)说这些评论已经得到支持,我很惊讶当我运行doxywizard时,我收到的错误如"警告:复合公司::产品:: MyInterface是没有记录".

这让我相信我在某种程度上误解了XML文档(希望不是,根据MSDN,我说的是正确的事情),或者我错误配置了doxywizard.

我首先通过向导选项卡运行doxywizard,并指定我想支持C#/ Java.当我运行它时,我的HTML页面是空白的,大概是因为前面提到过的警告.然后我尝试通过专家选项卡指定单个文件并再次运行 - 相同的行为.

任何人都可以告诉我什么开关或设置我缺少得到doxygen来生成HTML？

以下是我的界面中记录的属性/方法的示例:

/// <summary>
/// Retrieve the version of the device
/// </summary>
String Version { get; }

/// <summary>
/// Does something cool or really cool
/// </summary>
/// <param name="thing">0 = something cool, 1 = something really cool</param>
void DoSomething( Int32 thing);

我在界面上面有一条评论,如下所示:

/// <summary>
/// MyInterface
/// </summary>
public interface MyInterface {...}

VS 有一个复选框，仅从 C# 构建 XML 文档文件。我在 JetBrains Rider 的构建设置中找不到类似的内容。做到这一点最简单的方法是什么？

当您创建在Visual Studio C#方法XML文档(我使用的是2010),您会收到用于创建各种XML标记,如见,paramref等.另一方面,当你在AA CREF属性添加智能感知支持你必须使用a,我认为是复杂的格式来描述类型.当你有许多泛型时,这是最糟糕的.

我正在寻找的是如下.如果要在see元素中设置cref属性,则会有一个Intellisense类列表,这些类与您到目前为止输入的类相匹配,然后输出必要的正确类型描述.或者,当您在paramref元素上设置cref属性时,您会收到该方法的参数列表.

有没有人知道Visual Studio的某些插件,为这些cref属性提供Intellisense？

我正在使用Sandcastle帮助文件生成器将我的C#XML-DOC文件输出为网站格式.如何从命令行完成相同的操作,以便在构建实际项目时可以在Visual Studio中将其添加为构建事件？

最终目标是在构建Visual Studio项目时构建网站帮助文件内容.

C#语言规范的附录A涉及文档注释,它指出有两种形式:

single-line-doc-comment:
/// input-charactersopt
delimited-doc-comment:
/**delimited-comment-textopt*/

有偏好吗？我注意到倾向于选择单行文档评论格式,但我不知道除了人们从美学观点选择之外是否存在技术或实践原因.

我还在Jones和Freeman的"C#for Java Developers"一书中读到了以下内容:

代码文档注释前面有三个正斜杠,如下所示:
/// A single line documentation comment.
C#规范还建议使用熟悉的/**标记来标识多行文档注释.但是,C#编译器的7.00版本不支持此语法.

我一直无法验证csc的最新版本是否与多行语法不兼容.据我所知,这种语法运行得很好.

**edit**有人要求展示样品.这是样本:

/// <summary>
/// Performs a Method1 calculation on two strings
/// </summary>
/// <param name="arg1">The first string</param>
/// <param name="arg2">The second string</param>
/// <returns>The number 3</returns>
public static int Method1(String arg1, String arg2)
{
    return 3;
}
/**
 * <summary>
 * Performs a Method2 calculation on two strings
 * </summary>
 * <param name="arg1">The first string</param>
 * <param name="arg2">The second …

在 .NET Core 应用程序中，如果我这样做

typeof(DateTime).Assembly.Location

我得到

C:\Program Files\dotnet\shared\Microsoft.NETCore.App\3.1.4\System.Private.CoreLib.dll

但是DateTime 结构的文档说程序集是System.Runtime.dll

我正在尝试查找 .xml 文件的 XML 文档文件DateTime。我System.Private.CoreLib.xml在我的系统上找不到 a ，但 aSystem.Runtime.xml确实System.Runtime.dll在其文件夹中随文件一起存在（根据 XML 文档约定）。

如何System.Private.CoreLib.dll涉及到System.Runtime.dll？

我正在尝试使用 Roslyn 来获取 XML<Summary>标记内容（类似于 Visual Studio 中的悬停工具提示），但我看不到如何将类型与 XML 文档的位置相关联？