标签: sandcastle

我目前正在使用Sandcastle,Doxygen和JavaDoc为我编写的代码生成文档.是否可以使用这些包记录XML模式？如果没有,是否有任何(最好是免费!)包可以做到这一点？我可以自己编写文档作为Doxygen或Sandcastle中的额外概念主题,但我宁愿为我做一个工具!

一个例子是(虽然我不是XML Schema的专家!):

/// <summary>Top Node</summary>
<xs:element name="TopNode">
    /// <summary>Child Node</summary>
    <xs:element name="ChildNode" type="xs:string"/>
</xs:element>

如果类实现了接口中定义的方法,则可以选择是复制文档还是引用它<see cref="..." />.

public interface IPerformer
{
    /// <summary>
    /// Do something useful.
    /// </summary>
    /// <param name="something">Object to do something with</param>
    void Do(Something something);
}

public class Implementation : IPerformer
{
    /// <copy from="IPerformer" /> # that is what I want!
    public void Do(Something something)
    {
        // implementation ...
    }
}

是否有可能让API文档工具(Sandcastle)自动复制文档(什么会使阅读API文档更加舒适)？@inheritDoc来自Java Doc的东西？

基本上,我有以下代码:

public class MyDictionary<TKey, TValue> : IDictionary<TKey, TValue>
{
    /// <summary> My Summary </summary>
    void MyDictionary<TKey, TValue>.ICollection<KeyValuePair<TKey, TValue>> { ... }
}

MyProject.XML

<member name="M:MyProject.MyDictionary`2.System#Collection#Generic#ICollection{System#Collections#Generic#KeyValuePair{TKey@TValue}}#Clear">
 <summary>
  My Summary
 </summary>
</member>

Sandcastle的内置输出:

警告:ShowMissingComponent:缺少M:MyProject.MyDictionary`2.System#Collections的文档#Generic#ICollection {T} #Clear

所以,不知道该怎么做.我也有我的沙堡构建选项包括明确的实现,这就是为什么它创建的文档中为他们的网页,但它似乎无法弄清楚,我没有创建此方法XML注释.奇怪的是,该void MyDictionary<TKey, TValue>.IDictionary<TKey, TValue>.Add(TKek key, TValue value)方法被识别为具有XML注释.实际上,所有隐式实现的ICollection>方法都给Sandcastle一个问题.有帮助吗？

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

如何在SandCastle帮助文件生成器生成的文档中省略某些公共类或方法？

示例:我有以下具有两个公共方法的公共类:

/// <summary>
/// A simple test class.
/// </summary>
public class MyClass
{
    /// <summary>
    /// Method1s this instance.
    /// </summary>
    public void Method1()
    {
        // Do some operations here.
    }

    /// <summary>
    /// Method2s this instance.
    /// </summary>
    public void Method2()
    {
        // Do some operations here.
    }
}

当我使用SandCastle帮助文件生成器从此代码生成帮助文件时,我想忽略Method2.

我有一个类,我想创建一个关于如何使用的简单示例.但是,当我在类声明中使用标记时,该示例不会出现在Sandcastle输出中.它适用于对象的成员,但不适用于类本身.沙堡可以处理吗？

我想做的一个例子是.

MSDN TcpClient文档

这有一个关于如何使用该类的示例.我怎样才能在课堂上加入这样的东西？

我想这样做:

/// <summary> My example class </summary>
/// <example>
///   <code>
///      // Example code on how to use the class
///   </code>
/// </example>
public class MyClass
{
    public string MyString {get;set;}
}

是否可以从与您编写摘要的方法不同的方法引用参数,如果是,则语法是什么.

我知道<paramref name="..."/>但我不知道如何从不同的方法中引用.

简单幽默的例子,以防我不清楚:

/// <summary>
/// Does magical Foo things!
/// </summary>
/// <param name="magic">Magic Toggle!</param>
public void Foo(bool magic)
{
    //...
}

/// <summary>
/// Does Bar things. More down to earth, no <paramref name="Foo(bool).magic"/> involved!
/// </summary>
public void Bar()
{
    //...
}

(显然以上不是一个很好的用例,它只是出于插图目的.)

在XML文档中对C#的注释中,有没有办法将两个或多个函数标记为彼此重载,以便它们自动引用？理想情况下,它们也会以某种方式分组在沙堡生成的文档中.

目的:通常,我想链接到这组功能,例如在效用函数列表中,只提一个重载,并使其他功能很容易从那里发现.

目前我正在添加链接,但这很乏味.

我们使用 Sandcastle 来提供概念文档，并希望以非 CHM 或 HTML 形式（即打印形式）向客户提供文档。它可以是 Word 或 PDF，可以简单地附加到电子邮件中。用例通常涉及想要发送主题的人。

我们能做的最好的事情就是在查看 HTML 时从 CHM 查看器打印或从 Chrome 打印为 PDF。它们存在一些问题，因为它们会删除锚元素点击、将图像变成黑白等。

Codeplex 上的 SHFB 讨论中有一个帖子指出没有任何已知的替代方案 - http://shfb.codeplex.com/discussions/260489。我在这里重新发布问题，希望获得更多的意见和可见度。

如何使用<inheritdoc/>从另一个方法继承特定异常。是否可以做这样的事情：

/// <summary>
/// Summary
/// </summary>
/// <inheritdoc cref="Method2(int)" select="exception[@cref='CustomException']" />
public int Method1()
{
    return Method2(1);
}

/// <summary>
/// Summary...
/// </summary>
/// <exception cref="ArgumentException">
/// ArgumentException...
/// </exception>
/// <exception cref="CustomException">
/// CustomException...
/// </exception>
public int Method2(int count)
{
    // do something
}

当我构建文档并打开它时，Method1 也不例外。目前，我的解决方法是添加id="CustomException"到 Method2 并使用<inheritdoc cref="Method2(int)" select="exception[@id='CustomException']" />