Генерация структурированной документации из закомментированного кода - PullRequest
Новая
       21

Генерация структурированной документации из закомментированного кода

0 голосов
/ 18 апреля 2019

Как мне получить Asciidoc (tor) для генерации, например. хорошее общее описание функции из нескольких комментариев кода и некоторого кода, включая сигнатуру функции, без разделки моего кода тегами?

AFAIK Asciidoc поддерживает только внешние включения в свой файл Asciidoc через окружающие теги в коде, подобном 

# tag::mytag[] 
<CODE TO INCLUDE HERE>
# end::mytag[]

, что было бы довольно шумно вокруг каждого описывающего комментария в пределах одного тела функции и вокруг каждой сигнатуры функции. Возможно, существует экзотический, менее многословный способ, такой как маркировка однострочных комментариев, таких как #!, и однострочных тегов, которые указывают Asciidoctor читать только одну строку относительно этих тегов.

Рассмотрим этот крошечный пример. 

def uber_func(to_uber: str) -> str:
    """
    This is an overall description. Delivers some context.
    """

    # Trivial code here

    # To uber means <include code below>
    result = to_uber + " IS SOOO " + to_uber + "!!!"

    # Trivial code here

    # Function only returns upper case.
    return result.upper()

Мой наивный подход Asciidoc, включающий все значащие комментарии, строку документации и сигнатуру функции из приведенного выше кода, выглядел бы замечательно, плюс, Asciidoc не распознает и не удаляет отметки комментариев, поэтому итоговая документация может быть не такой привлекательной.

Вместо этого очень уродливо 

# tag::uber_func[]
def uber_func(to_uber: str) -> str:
    """
    This is an overall description. Delivers some context.
    """
# end::uber_func[]

    # Trivial code here

    # tag::uber_func[]
    # To uber means
    result = to_uber + " IS SOOO " + to_uber + "!!!"
    # end::uber_func[]

    # Trivial code here

    # tag::uber_func[]
    # Function only returns upper case.
    # end::uber_func[]
    return result.upper()

Я хотел бы использовать что-то вроде (псевдо): 

def uber_func(to_uber: str) -> str:
    # tag::uber_func[readline:-1,ignore-comment-marks,doc-comment:#!]
    #! This is an overall description. Delivers some context.

    # Trivial code here

    #! To uber means
    # tag::uber_func[readline:+1]
    result = to_uber + " IS SOOO " + to_uber + "!!!"

    # Trivial code here

    #! Function only returns upper case.
    return result.upper()
    # end::uber_func[]

Я думаю, что общая проблема в том, что Asciidoc - это просто инструмент форматирования текста , что означает, что, если я хочу, чтобы он генерировал структурированную документацию в основном из моего кода, мне нужно предоставить эту структуру в мой код и в моем файле .adoc. Генераторы документации, такие как Doxygen на другой стороне, автоматически распознают эту структуру , а комментарии документируют . Я очень ценю эту функцию, так как некоторые генераторы позволяют вам писать код и красивую документацию бок о бок, что значительно снижает общие усилия. Если Asciidoc не позволит мне сделать это разумным образом, мне придется искать что-то еще.

1 Ответ

0 голосов
/ 29 апреля 2019

Я думаю, вам нужно написать скребок, который помещает комментарии в структуру, а затем вставить эту структуру в ваш AsciiDoc. Таким образом, комментарии могут быть внутренне отформатированы с помощью разметки AsciiDoc, и вы можете выводить их в документы, сгенерированные Asciidoctor, но вам не понадобится Asciidoctor для непосредственного чтения исходных файлов.

Я бы попробовал систему использования одного # для неопубликованных комментариев и ## для тех, которые вы хотите опубликовать, или наоборот, или добавьте a # к тем, которые для публикации документов. Как и те, которые обозначены знаком """. Затем ваш скребок может прочитать имя блока (uber_func или любую другую важную часть), а затем очистить комментарии хранителя и весь буквальный код, разместив их все в файле. В приведенном ниже файле большинство комментариев помечено как text, комментарии не сохранены, а содержимое без комментариев - code: 

# tag::function__uber_func[]
# tag::function__uber_func_form[]
uber_func(to_uber: str) -> str:
# end::function__uber_func_form[]
# tag::function__uber_func_desc[]
This is an overall description. Delivers some context.
# end::function__uber_func_desc[]
# tag::function__uber_func_body[]
# tag::function__uber_func_text[]
To uber means
# end::function__uber_func_text[]
# tag::function__uber_func_code[]
----
result = to_uber + " IS SOOO " + to_uber + "!!!"
----
# end::function__uber_func_code[]
# tag::function__uber_func_text[]
Function only returns upper case.
# end::function__uber_func_text[]
# tag::function__uber_func_code[]
----
return result.upper()
----
# end::function__uber_func_code[]
# end::function__uber_func[]

Я знаю, это выглядит отвратительно, но это супер полезно для шаблона AsciiDoc. Например, используйте просто: 

uber_func::
include::includes/api-stuff.adoc[tags="function__uber_func_form"]
+
include::includes/api-stuff.adoc[tags="function__uber_func_desc"]
+
include::includes/api-stuff.adoc[tags="function__uber_func_body"]

Это было бы еще лучше, если вы проанализируете его в формате данных (например, JSON или YAML) и затем динамически вставите его в шаблон AsciiDoc. Но вы могли бы поддерживать что-то подобное, если бы оно не было слишком массивным. При определенном размере (более 20 таких записей?) Вам нужен промежуточный источник данных (файл эфемерных данных, получаемый в результате скребкования), а в определенном более крупном масштабе (> 100 кодовых блоков / конечных точек?) Вам, вероятно, нужна система, которая специализируется в документации API, такой как Doxygen и др.

...