AsciiDoc Включить только значения из пользовательской аннотации

Question

Я хотел бы задокументировать мой проект, используя AsciiDoc.

У меня есть класс, подобный приведенному ниже, который содержит комментарии, в которых описываются некоторые детали о шагах, обрабатываемых методом. Я хотел бы сделать эти комментарии содержимым некоторых разделов моего .adoc.

public RequestResponse processRequest(UserRequest request){ 
    /* First retrieve info from db calling the stored procedure 
     dbo.StoredProcedure with input parameters A,B,C */ 
    DbResponse dbResponse = dao.getResponse(request); 

    // Call method to calculate all scenarios for the Example request 
    CalcResult calcResult = util.calculateStuff(request.getAmountList()); 

    /* Format the response to include the fields from the calcResult as well 
     as the request details returned from the DB result set */ 
    return util.formatResponse(dbResponse,calcResult); 
} 

В конечном счете эта документация затем будет использоваться для обеспечения других разработчиков наброски, как некоторые REST называет процесс без них, чтобы идти в исходный код и посмотреть на все шаги.

Я новичок в AsciiDoc и может быть вне базы с этим прецедентом.

Answer 1

Несмотря на то, что изначально вы не задавали формальный вопрос, я считаю, что явная цель документирования (REST) ​​API, использующего AsciiDoc, благородна, поэтому для ваших потенциальных вопросов я попытаюсь указать вам на перспективные направления:

Q: Что было бы подходящим форматом для комментариев документации в целом?

A: Javadoc. Ваш язык программирования похож на C++ или Java. Популярным стандартом для формата автоматически извлекаемых комментариев является формат JavaDoc. Префиксные комментарии, начинающиеся с двух звездочек и комментариев в конце строки, начиная с трех, а не из двух косых черт, предназначены для генератора документации: /** Prefixed API doc */ int foo; /// postfixed API doc Использование Javadoc дает преимущество в том, что существует много существующих инструментов, которые понимают это соглашение, в частности среды разработки (IDE).

Q: Существуют ли существующие процессоры, которые извлекают такие комментарии к документации?

A: Javadoc сам (предположим только Я), Doxygen (языки C-Like), Asciidoclet [1] [2]. Asciidoclet - это Doclet [3], который является своего рода плагином для обычного Javadoc, который обычно каким-то образом интегрируется в вашу среду IDE. Asciidoclet понимает asciidoc, а точнее синтаксис asciidoctor, внутри комментариев к документу. Вы можете перепрофилировать некоторые из этих компонентов процессоров для своих нужд.

Q: Что считается лучшей практикой при регистрации API REST?

A: Вы быстро увидите, что Swagger (http://swagger.io/) популярен для документации REST API. Но он не использует asciidoc.

Q: Как я могу использовать разметку asciidoc для документирования моего API?

A: Поиск в сети для «использования asciidoc для документирования API». Посмотрите на верхние ссылки. Вы обнаружите, что некоторые люди добились определенных успехов в примирении Джавадока с Swagger и Asciidoc. Однако мне кажется, что они не знали об Asciidoclet.

• [1] https://github.com/asciidoctor/asciidoclet
• [2] http://asciidoctor.org/news/2013/06/03/asciidoclet-announcement/
• [3] https://en.wikipedia.org/wiki/Doclet