documentation - protobuffers - ¿Generar documentación de protobuf?

protocol buffer list

Question

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

Answer 1

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

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

Answer 2

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

Answer 3

Doxygen es compatible con los denominados filtros de entrada, que le permiten transformar el código en algo que el doxygen entiende. Escribir un filtro de este tipo para transformar la IDL de Protobuf en código C ++ (por ejemplo) le permitiría usar todo el poder de Doxygen en los archivos .proto. Vea el artículo 12 de las Preguntas Frecuentes de Doxygen .

Hice algo similar para CMake, el filtro de entrada simplemente transforma las macros y funciones de CMake en declaraciones de función C. Puedes encontrarlo here .

Answer 4

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

Answer 5

En Protobuf 2.5, los comentarios "//" que colocas en tus archivos .proto realmente lo hacen en el código fuente Java generado como comentarios Javadoc. Más específicamente, el compilador protoc tomará sus "//" comentarios de esta manera:

// 
// Message level comments
message myMsg {

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

entrará en sus archivos de origen Java generados. Por alguna razón, protoc encierra los comentarios de Javadoc en <pre> etiquetas <pre> . Pero en general es una nueva característica agradable en v2.5.

Answer 6

Un complemento protobuf de código abierto que genera DocBook y PDF a partir de los archivos proto.

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

Descargo de responsabilidad: Soy el autor del plugin.

Answer 7

[ Actualización : agosto de 2017. Adaptado a la reescritura completa de Go de protoc-gen-bug, actualmente 1.0.0-rc ]

El protoc-doc-gen , creado por @estan (ver también su respuesta anterior ) proporciona una manera buena y fácil de generar su documentación en html, json, markdown, pdf y otros formatos.

Hay una cantidad de cosas adicionales que debo mencionar:

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

El repositorio ya está 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 del protocolo Dat Project Hypercore en un formato agradable.

Puede ver varias opciones de generación de resultados html y markdown en (o busque here un ejemplo de markdown en SO):

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

El script TravisCI que realiza toda la automatización es este simple archivo .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 : El protocolo de hypercore es una de las especificaciones principales del ecosistema de módulos Dat Project para crear aplicaciones descentralizadas de igual a igual. Utilicé su archivo .proto para demostrar conceptos )

Answer 8

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

Mensajes autodescriptivos

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

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

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

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

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

Al usar clases como DynamicMessage (disponible en C ++ y Java), puede escribir herramientas que pueden manipular los mensajes de autodescripción.

Dicho todo esto, la razón por la que esta funcionalidad no está incluida en la biblioteca de Protocol Buffer es porque nunca hemos tenido un uso dentro de Google.