Подтвердить что ты не робот

Создать документацию Protobuf?

Кто-нибудь знает хороший инструмент для создания документации Google Protobuf с использованием исходных файлов .proto?

4b9b3361

ОТВЕТЫ

Ответ 1

Плагин protobuf с открытым исходным кодом, который генерирует DocBook и PDF из прото файлов.

http://code.google.com/p/protoc-gen-docbook/

Отказ от ответственности: я являюсь автором плагина.

Ответ 2

В дополнение к ответу askldjd, я хотел бы указать свой инструмент на https://github.com/estan/protoc-gen-doc. Это также плагин компилятора буфера протокола, но он может генерировать HTML, MarkDown или DocBook из коробки. Он также может быть настроен с использованием шаблонов Mustache для создания любого текстового формата, который вам нравится.

Комментарии к документации записываются с использованием /** ... */ или /// ....

Ответ 3

[ Обновление: август 2017. Адаптировано к полной переписке Go для protoc-gen-bug, в настоящее время 1.0.0-rc ]

protoc-doc-gen, созданный @estan (см. Также его предыдущий ответ), предоставляет хороший и простой способ генерировать вашу документацию в html, json, markdown, pdf и других форматах.

Есть ряд дополнительных вещей, которые я должен упомянуть:

  1. Estan больше не является protoc-doc-gen, но является псевдомуто
  2. В отличие от того, что я читал на разных страницах, в комментариях можно использовать богатое встроенное форматирование (полужирный/курсив, ссылки, фрагменты кода и т.д.).
  3. protoc-gen-doc был полностью переписан в Go и теперь использует Docker для генерации (вместо apt-get)

Хранилище теперь здесь: https://github.com/pseudomuto/protoc-gen-doc

Чтобы продемонстрировать второй момент, я создал пример репозитория для автоматической генерации документации Dat Project Hypercore Protocol в хорошем формате.

Вы можете просмотреть различные варианты генерации вывода html и markdown (или посмотрите здесь пример уценки в SO):

Сценарий TravisCI, который выполняет всю автоматизацию, - это простой файл .travis.yml:

sudo: required

services:
  - docker

language: bash

before_script:
  # Create directory structure, copy files
  - mkdir build && mkdir build/html
  - cp docgen/stylesheet.css build/html

script:
  # Create all flavours of output formats to test (see README)
  - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/html:/protos:ro pseudomuto/protoc-gen-doc
  - docker run --rm -v $(pwd)/build/html:/out -v $(pwd)/schemas/html:/protos:ro -v $(pwd)/docgen:/templates:ro pseudomuto/protoc-gen-doc --doc_opt=/templates/custom-html.tmpl,inline-html-comments.html protos/HypercoreSpecV1_html.proto
  - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/md:/protos:ro pseudomuto/protoc-gen-doc --doc_opt=markdown,hypercore-protocol.md
  - docker run --rm -v $(pwd)/build:/out -v $(pwd)/schemas/md:/protos:ro -v $(pwd)/docgen:/templates:ro pseudomuto/protoc-gen-doc --doc_opt=/templates/custom-markdown.tmpl,hypercore-protocol_custom-template.md protos/HypercoreSpecV1_md.proto

deploy:
  provider: pages
  skip_cleanup: true          # Do not forget, or the whole gh-pages branch is cleaned
  name: datproject            # Name of the committer in gh-pages branch
  local_dir: build            # Take files from the 'build' output directory
  github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard (see README)
  on:
    all_branches: true        # Could be set to 'branch: master' in production

(PS: протокол HyperCore является одной из основных спецификаций экосистемы модулей Dat Project для создания децентрализованных одноранговых приложений. Я использовал их файл .proto для демонстрации концепций)

Ответ 4

Doxygen поддерживает так называемые входные фильтры, которые позволяют преобразовывать код во что-то, что понимает doxygen. Написание такого фильтра для преобразования Protobuf IDL в код С++ (например) позволит вам использовать всю полноту Doxygen в файлах .proto. См. Пункт 12 Doxygen FAQ.

Я сделал что-то подобное для CMake, входной фильтр просто преобразует макросы CMake и функции в объявления функций C. Вы можете найти здесь здесь.

Ответ 5

Тема старая, но вопрос по-прежнему актуален. У меня были очень хорошие результаты с doxygen + proto2cpp. Proto2cpp работает как входной фильтр для Doxygen.

Ответ 6

Поскольку файл .proto - это просто просто объявление, я обычно считаю, что исходный файл с встроенными комментариями является простой и эффективной документацией.

Ответ 7

В Protobuf 2.5 комментарии "//", которые вы помещаете в ваши .proto файлы, фактически превращают их в сгенерированный исходный код Java как комментарии Javadoc. Более конкретно, компилятор protoc примет ваши комментарии "//" следующим образом:

// 
// Message level comments
message myMsg {

    // Field level comments
    required string name=1;
}

войдет в ваши сгенерированные исходные файлы Java. По какой-то причине protoc заключает комментарии Javadoc в тегах <pre>. Но в целом это хорошая новая функция в версии 2.5.

Ответ 8

https://code.google.com/apis/protocolbuffers/docs/techniques.html

Самоописательные сообщения

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

Однако обратите внимание, что содержимое файла .proto может быть представленный с использованием протокольных буферов. Файл src/google/protobuf/descriptor.proto в пакете исходного кода определяет связанные типы сообщений. protoc может выводить FileDescriptorSet - представляет собой набор файлов .proto - используя --descriptor_set_out. При этом вы можете определить самоописательное сообщение протокола, например:

message SelfDescribingMessage {//Набор файлов .proto, которые определяют типа. требуется FileDescriptorSet proto_files = 1;

//Имя типа сообщения. Должен быть определен одним из файлов в //proto _files. обязательная строка type_name = 2;

//Данные сообщения. обязательные байты message_data = 3; }

Используя такие классы, как DynamicMessage (доступно на С++ и Java), вы затем могут писать инструменты, которые могут манипулировать сообщениями SelfDescribingMessages.

Все, что сказано, причина, по которой эта функциональность не включена в библиотека Buffer Protocol - это потому, что мы никогда не использовали ее внутри Google.