Question

我正在寻找从Javascript和C＃（原则上为任何语言）将文档生成一个数据集并从中生成网站的方法。我想以XML格式存储从JS / C＃代码中提取的信息，并立即在（定制的）网站生成器中使用该信息，或将其存储以供以后使用/存档：

code comments in programming languages --> XML documents --> website

如果XML格式受模式限制并被接受为标准，则它们更有用，所以我的问题是；

是否有关于代码的XML文档的标准或DTD / XSD / RNG模式？

我看过C# XML documentation comments，但这并不是要存储为XML文件，而只是“多余的”，我的意思是说最重要的信息（例如类名）没有记录在案在里面。我对编译器生成的XML文档文件一无所知。
类似的JSDoc或documentationjs很有用，可以用来生成JSON文件。您可以将其转换为XML，但这几乎不是标准。
DITA Programming domains，这些元素可以用在相当非结构化的文本流中，但实际上并不能形成代码的统一描述
OpenAPI/Swagger文档对于REST端点来说相当不错

合适的XML格式应该能够描述代码概念，例如函数，类，类型常量（可以是原始类型或对另一个XML文档的引用），公共/私有/静态成员，参数和返回值值。拥有诸如手写的描述，示例，导入/依赖项/版本等之类的额外信息会很不错。

过去，我想出了以下示例来解决我的问题。它描述了一个带有两个参数的函数，其中第一个可以是字符串或字符串数组：

<type>
    <name>askQuestionOnStackOverflow</name>
    <source>src/help/askQuestionOnStackOverflow.js</source>
    <restrict>
        <type base="function" />
    </restrict>
    <description>
        <paragraph>Ask a question on SO, and hope you're not embarressing yourself.</paragraph>
    </description>
    <arguments>
        <type>
            <name>question</name>
            <restrict join='or'>
                <type base='string' />
                <type base='array'>
                    <restrict>
                        <type base='string' />
                    </restrict>
                </type>
            </restrict>
            <description>
                <paragraph>The question, or the questions you would like to ask</paragraph>
            </description>
        </type>
        <type>
            <name>user</name>
            <restrict>
                <type reference="../classes/User.xml" />
            </restrict>
            <description>
                <paragraph>The user that asks the question</paragraph>
            </description>
        </type>
    </arguments>
</type>

可能从中生成上述内容的Javascript源代码如下：

/**
 * Ask a question on SO, and hope you're not embarressing yourself.
 * @param {string|string[]}  question  The question, or the questions you would like to ask
 * @param {User}             user      The user that asks the question
 */
function askQuestionOnStackOverflow (question, user) {

}

什么是好的代码文档XML模式？

0 个答案: