Что такое хорошая XML-схема документации документации? - PullRequest
Новая
       47

Что такое хорошая XML-схема документации документации?

0 голосов
/ 02 июня 2019

Я хочу сгенерировать документацию из Javascript и C # (в принципе, любого языка) в один набор данных и создать веб-сайт из этого.Я хотел бы сохранить информацию, извлеченную из кода JS / C #, в формате XML и немедленно использовать ее в (на заказ) генераторе сайта или сохранить ее для дальнейшего использования / архивирования: 

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

Форматы XML более удобны, если они ограничены схемой и приняты в качестве стандарта, поэтому мой вопрос:

Существует ли стандартная или DTD / XSD / RNG-схема для XML-документов о коде?

  • Я смотрел комментарии к документации C # XML , но он не предназначен для хранения в виде файлов XML и является лишь «дополнительным», под которым я хочу сказать, что наиболее важныйинформация (такая как имя класса) не документирована в нем.У меня нет никаких знаний о сгенерированном компилятором XML-файле документации.
  • Возможно, аналогично, JSDoc или documentationjs полезны и могут быть использованы для генерации JSONфайл.Вы можете преобразовать это в XML, но это вряд ли стандарт.
  • Домены программирования DITA , которые являются элементами, которые могут использоваться в довольно неструктурированном потоке текста, но на самом деле не образуютсвязное описание кода
  • 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) {

}
...