Как мне получить 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 не позволит мне сделать это разумным образом, мне придется искать что-то еще.