¿Generar documentación de Protobuf?

Question

¿Alguien sabe de una buena herramienta para generar documentación de Google Protobuf utilizando los archivos fuente .proto?

Answer 1

Doxygen admite los llamados filtros de entrada, que le permiten transformar el código en algo que doxygen entiende. Escribir dicho filtro para transformar Protobuf IDL en código C++ (por ejemplo) le permitiría usar toda la potencia de Doxygen en archivos .proto. Ver el artículo 12 del Doxygen FAQ.

Hice algo similar para CMake, el filtro de entrada solo transforma las macros y funciones de CMake en declaraciones de función C. Lo puedes encontrar here.

Answer 2

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

Mensajes auto-descripción

Protocol Buffers no contienen descripciones de sus propios tipos. Por lo tanto, dando solo un mensaje en bruto sin el correspondiente archivo .proto definiendo su tipo, es difícil extraer datos útiles.

Sin embargo, tenga en cuenta que el contenido de un archivo .proto puede ser representado utilizando búferes de protocolo. El archivo src/google/protobuf/descriptor.proto en el paquete de código fuente define los tipos de mensajes implicados. El protocolo puede generar un archivo FileDescriptorSet, que representa un conjunto de archivos .proto, utilizando la opción --descriptor_set_out. Con esto, puede definir un mensaje de protocolo de autodescripción como lo siguiente:

mensaje SelfDescribingMessage {// Conjunto de archivos .proto que definen el tipo. requerido FileDescriptorSet proto_files = 1;

// Nombre del tipo de mensaje. Debe estar definido por uno de los archivos en // proto_files. string requerido type_name = 2;

// Los datos del mensaje. bytes requeridos message_data = 3; }

Al utilizar clases como DynamicMessage (disponible en C++ y Java), puede escribir herramientas que pueden manipular SelfDescribingMessages.

Dicho todo esto, la razón de que esta funcionalidad no esté incluida en la biblioteca de Protocolo de búfer se debe a que nunca hemos tenido uso de ella dentro de Google.

Answer 3

Dado que el archivo .proto es principalmente una declaración, normalmente me parece que el archivo fuente con comentarios en línea es una documentación sencilla y efectiva.

Answer 4

Un plugin protobuf de fuente abierta que genera DocBook y PDF a partir de los archivos proto.

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

responsabilidad: yo soy el autor del plugin.

Answer 5

En Protobuf 2.5, los comentarios "//" que coloca en sus archivos .proto realmente lo convierten en el código fuente java generado como comentarios de Javadoc.Más específicamente, el compilador protoc tomará sus comentarios "//" como esto:

// 
// Message level comments 
message myMsg { 

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

voy a entrar en los archivos fuente de Java generados. Por algún motivo, el protocolo incluye los comentarios de Javadoc en las etiquetas <pre>. Pero, en general, es una nueva característica agradable en v2.5.

Answer 6

El hilo es antiguo, pero la pregunta todavía parece relevante. He obtenido muy buenos resultados con Doxygen + proto2cpp. proto2cpp funciona como un filtro de entrada para Doxygen.

Answer 7

Además de la respuesta de askldjd, me gustaría señalar mi propia herramienta al https://github.com/estan/protoc-gen-doc. También es un plugin de compilador de buffer de protocolo, pero puede generar HTML, MarkDown o DocBook de fábrica. También se puede personalizar utilizando plantillas de bigote para generar cualquier formato basado en texto que desee.

Los comentarios de la documentación se escriben usando /** ... */ o /// ....

Answer 8

[actualización: Aug 2017. Adaptado a la reescritura completa Ir de protoc generación de errores, actualmente 1.0.0-rc]

El protoc-doc-gen, creado por @estan (ver también his earlier answer) proporciona una forma buena y fácil para generar su documentación en html, json, markdown, pdf y otros formatos.

Hay una serie de cosas adicionales que debo mencionar:

1. estan ya no es el mantenedor de protoc-doc-gen, pero es pseudomuto
2. A diferencia de lo que he leído en varias páginas que es posible utilizar el formato enriquecido en línea (negrita/cursiva, enlaces, fragmentos de código, etc.) dentro de los comentarios
3. protoc-gen-doc ha sido completamente reescrito en Ir y ahora usa Docker para la generación (en lugar de apt-get)

El repositorio está ahora aquí: https://github.com/pseudomuto/protoc-gen-doc

Para demostrar el segundo punto he creado un repositorio de ejemplo para generar automáticamente la documentación Dat Project Protocolo HyperCore en un formato agradable.

Puede ver varias html y markdown opciones de generación de salida en (o buscar here para un ejemplo de reducción del precio de SO):

• https://github.com/aschrijver/protoc-gen-doc-example

El guión TravisCI que hace toda la automatización es la siguiente simple .travis.yml file:

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: El protocolo hypercore es una de las especificaciones principales del Dat Project ecosistema de módulos para la creación de aplicaciones descentralizadas punto a punto.Solía ​​su archivo .proto para demostrar conceptos)