标签: xml-documentation

编写可以使用的xml文档时<see cref="something">something</see>,当然可以使用.但是,如何引用具有泛型类型的类或方法？

public class FancyClass<T>
{
  public string FancyMethod<K>(T value) { return "something fancy"; }
}

如果我要在某处写xml文档,我将如何引用这个花哨的类？我该如何参考FancyClass<string>？方法怎么样？

例如,在另一个类中,我想让用户知道我将返回一个实例FancyClass<int>.我怎么能看到cref的东西呢？

这应该更容易...

我想在我的代码中为XML文档添加"编码"换行符

/// <summary>
/// Get a human-readable variant of the SQL WHERE statement of the search element. &lt;br/&gt;
/// Rather than return SQL, this method returns a string with icon-tokens, which 
/// could be used to represent the search in a condensed pictogram format.
/// </summary>

如您所见,我找到了一些答案,证明添加了<和>括号.有趣的是,好的'ol <br />换行符不会在Intellisense弹出窗口中创建换行符.

我发现这很烦人......

有什么建议？

将XmlDoc集成到Web Api项目中的文档似乎只处理所有API类型都属于WebApi项目的情况.特别是,它讨论了如何将XML文档重新路由到App_Data/XmlDocument.xml取消注释配置中将使用该文件的行.这隐含地只允许一个项目的文档文件.

但是,在我的设置中,我在一个常见的"模型"项目中定义了我的请求和响应类型.这意味着如果我有一个端点,例如:

[Route("auth/openid/login")]
public async Task<AuthenticationResponse> Login(OpenIdLoginRequest request) { ... }

在OpenIdLoginRequest单独的C#项目中定义的位置如下:

public class OpenIdLoginRequest
{
    /// <summary>
    /// Represents the OpenId provider that authenticated the user. (i.e. Facebook, Google, etc.)
    /// </summary>
    [Required]
    public string Provider { get; set; }

    ...
}

尽管有XML文档,但request在查看特定于端点的帮助页面(即http://localhost/Help/Api/POST-auth-openid-login)时,参数的属性不包含任何文档.

如何在Web API XML文档中显示具有XML文档的子项目中的类型？

是否有自动方式在界面与其实现之间同步注释？我目前正在记录它们,并且不想手动保持它们同步.

更新:

考虑以下代码:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

当我创建这样的类:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

这里的评论没有显示:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

该<inheritDoc/>标签将完全产生沙堡的文件,但它并没有在智能感知提示工作.

请分享您的想法.

谢谢.

<see cref="switch" />,例如,不起作用 - 我收到编译警告: XML comment on ... has syntactically incorrect cref attribute 'switch'

感兴趣的人的背景......

/// <summary>Provides base functionality for hand-coded abstractions of API method wrappers, mostly those that abstract over
/// parameters that are required to be JSON-encoded.</summary>
public class FacebookArgs : Dictionary<String, Object>
{
    /// <summary>Initializes an instance of <see cref="FacebookArgs" />.</summary>
    public FacebookArgs() { }

    /// <summary>Intializes an instance of <see cref="FacebookArgs" />, that contains elements copied from <paramref name="dictionary "/>.</summary>
    /// <param name="dictionary"></param>
    public …

你会为命名空间编写xml-doc吗？如果是的话,如何以及在哪里？

我想,如果有可能,可能是一个几乎空的文件,如下所示:

/// <summary>
/// This namespace contains stuff
/// </summary>
namespace Some.Namespace
{

}

但那会有用吗？既然你......"声明",或者至少在所有其他文件中都使用了命名空间......如果你在同一个命名空间的其他地方写了一个xml文档,会发生什么？一个人会消失吗？或者他们会以某种方式合并？

Noda Time有一个问题,它所提供的XML文档文件也包含了所有内部和私有成员 - 这是一种耻辱.

幸运的是,Sandcastle帮助文件生成器有一个自定义构建组件 - IntelliSenseComponent在理论上它做了正确的事情.不幸的是,我无法弄清楚如何正确配置它.

文档给出了这个例子:

 <output includeNamespaces="false" namespacesFile="Namespaces"
   folder="{@OutputFolder}" />

和州:

上面给出的示例来自Sandcastle帮助文件构建器的配置文件.与其一起使用时,替换标记{@SHFBFolder}和{@OutputFolder}用于在文件路径中插入帮助文件构建器的文件夹和项目的输出文件夹.这些在构建时被替换为适当的值.如果在您自己的构建脚本中使用该组件,请分别将该标记替换为组件程序集和输出文件夹的相对路径或绝对路径.

好吧,我正在使用SHFB,所以我希望它可以工作.但是,除了绝对的工作之路,我无法获得任何其他东西.我试过了:

folder="."
folder="{@OutputFolder}"
folder="{@OutputFolder}XYZZY"
folder="{@OutputFolder}\XYZZY"
folder="{@OutputFolder}/XYZZY"
folder="{@OutputFolder}/XYZZY/"

(我只是使用XYZZY作为易于搜索的东西.)

看一下源代码,我希望我可以使用环境变量,但这不起作用:

folder="%CD%\XYZZY"

虽然这样做......

folder="%USERPROFILE%\XYZZY"

这有效:

folder="c:\users\jon\test\xyzzy"

...但我真的不想要一个绝对的路径名.

文档表明所有这一切都应该很简单......我错过了什么？

涉及的版本:

• SHFB:1.9.3.0
• Sandcastle:2.6.10621.1

为谓词助手类编写一些XML文档.但我无法弄清楚我可以参考一个Expression<Func<T, bool>>没有得到语法错误.它甚至可能吗？我试过这个:

<see cref="Expression{Func{T, bool}}"/>

但我得到一条红色的波浪线{T, bool}}.这有效:

<see cref="Expression{TDelegate}"/>

有人有线索吗？

更新:

给出的答案(我接受了)似乎确实奏效了.但是现在我已经开始收到很多关于无法解决的问题的警告.我有一个叫做类ExpressionBuilder<T>,其作品有Expression<Func<T, bool>>很多.所以我当然想在我的XML评论中引用它.

我尝试了两个我知道的版本:

<see cref="Expression&lt;Func&lt;T, Boolean&gt;&gt;"/>
<see cref="Expression{Func{T, Boolean}}"/>

但是没有工作.(在最后一个问题上,ReSharper下了一个蓝色的波浪形,{T,Boolean}}我在编辑过程中得到两个警告,我用过它时说:

1. 关于'blah blah'的XML注释具有无法解析的cref属性'Expression>'
2. 类型参数声明必须是标识符而不是类型.另请参见错误CS0081.

在我试图引用的某个地方有同样的问题Range<Nullable<DateTime>>(也Range<DateTime?>没有用.{}和with < >)

我不应该提到这些种类的仿制药吗？

我在C#中创建了一个"类库",它有许多带摘要的函数(XML文档注释).

例如

///<summary>
///Adds the two numbres
///</summary>
public void Add()
{
    //statements
}

如果我在同一个命名空间中使用该函数,它会显示摘要,但如果我在某些工作空间(解决方案)中将其添加为参考,则不显示摘要.

如果添加它作为参考,如何使其可见其他解决方案,并且wat可能是这个的原因？

/// <summary>
/// This method does something...
/// </summary>
public void DoSomething() 
{
    // code...
}

当使用该方法/类等...在不同的.dll中时,注释不会显示.