Question

我想记录我的源代码（C＃源代码），实际上我使用了定义的XML文档标记。我如何通过特定标签定义？

例如，我使用了很多Design by Contract断言。我想要文档部分对于先决条件，后置条件，不变量...... 编写如下文档应该是可以的：

/// <precond>arg != null</precond>
/// <postcond>return > 0</postcond>

既然我不是XML大师，你们（大师）的某个人可以建议我吗？

我尝试使用＆lt;包括＆gt;，但是（对我来说）正确构建文档是不可能的。

非常感谢

Answer 1

首先是very usefull description xml评论的可能性。

接下来，生成文档的应用程序必须知道您自己制作的标签。我目前还不知道可以使用其他属性或元素进行扩展的文档构建器。

Answer 2

使用NDoc构建文档及其 custom tags 可能是一种解决方案。 NDoc的一个问题是开发停止了一段时间。

Sandcastle also supports custom tags，我不确定这是否适用于Sandcastle Builder，如果这是一个问题。

两者都是通过自定义默认的XSL用于其转换来完成的，例如

<xsl:template match="myTag" mode="seealso-section">
    <h1 class="green">
         <xsl:value-of select="." mode="slashdoc"/>
    </h1>
    </xsl:template>     
    <xsl:template match="null" mode="slashdoc">
    <xsl:text> null reference (Nothing in Visual Basic) </xsl:text>
</xsl:template>

编译器构建的XML（csc.exe /doc）没有在标记中强制使用名称空间，因此您可以自由使用您喜欢的任何标记。

C＃文档 - 用户定义的标签

2 个答案: