标签: xml-documentation

有没有办法直接从Visual Studio中的代码文档生成可读文档文件？(也考虑2010年)

代码示例:

/// <summary>
/// Convert a number to string
/// </summary>
/// <param name="number">An integer number to be converted to string</param>
/// <returns>Number as string</returns>
/// <example>
/// <code>
///     var s = MyMethod(5);
/// </code>
/// </example>
/// <exception cref="Exception">In case it can't convert</exception>
/// <remarks>
/// Whatever
/// </remarks>
public string MyMethod(int number)
{
    return number.ToString();
}

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 文档的位置相关联？

我想知道是否可以在注释中引用动态泛型类名称并在IDE中有条件地解决它？

简单的基类示例:

// <summary>
// Retrieves all <T> members from the database.
// </summary>
public void GetAll<T>()
{
 //magic
}

如果我现在从这个类继承而恰好是类User,那么我想让IntelliSense将我的评论显示为"从数据库中检索所有用户成员".

这可能吗？

• 我正在使用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项目,这可能会改变,但我想知道它现在是否已经可用......如果没有,我一定会建议它.

TypeScript中是否已经支持XML文档？似乎没有,但也许我忽略了一些东西.

我想要这样的事情:

export class Point {
   /// <summary>This is a Point class.</summary>

    constructor (public x: number, public y: number) { 
        /// <summary>Creates a new Point object</summary>
        /// <param name="x"></param>
        /// <param name="y"></param>
    }
}

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

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类型？

我在Web Api 2.1(Visual Studio 2012 C#)中创建了一个应用程序,并使用XML文档创建了一个帮助页面.

我只想暴露一些控制器,而不是我的Web Api的所有控制器,但同时我不想从方法,类,属性等中删除注释.

如何在我的帮助中选择一些不显示的元素和其他元素？

提前致谢

当提供相同方法的多个重载时,我经常不得不重复该方法的描述,这违反了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。