Générer de la documentation Protobuf? [fermé]

un plugin protobuf open source qui génère DocBook et PDF à partir des fichiers proto.

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

Avertissement: je suis l'auteur du plugin.

en plus de la réponse de l'askldjd, j'aimerais souligner mon propre outil à https://github.com/estan/protoc-gen-doc . Il s'agit également d'un plugin de compilateur de tampon de protocole, mais il peut générer du HTML, du MarkDown ou du DocBook. Il peut également être personnalisé en utilisant des modèles de moustache pour générer n'importe quel format basé sur le texte que vous aimez.

Documentation les commentaires sont écrits en utilisant /** ... */ ou /// ... .

[ Mise À Jour : Août 2017. Adapté à la réécriture complète de protocole-gen-bug, actuellement 1.0.0-rc ]

le protoc-doc-gen , créé par @estan (voir aussi sa réponse précédente ) fournit un bon et facile moyen de générer votre documentation en html, json, markdown, pdf et d'autres formats.

il y a plusieurs autres choses que je devrais mentionner:

1. estan n'est plus le mainteneur de protoc-doc-gen , mais pseudomuto est
2. en contraste avec ce que j'ai lu sur diverses pages il est possible d'utiliser le formatage en ligne riche (gras/italique, liens, extraits de code, etc.) dans les commentaires
3. protoc-gen-doc a été complètement réécrit dans Go et utilise maintenant Docker pour la génération (au lieu de apt-get )

le dépôt est maintenant ici: https://github.com/pseudomuto/protoc-gen-doc

pour démontrer le second point, j'ai créé un référentiel d'exemple pour auto-générer la documentation dat Project Hypercore Protocol dans un format agréable.

vous pouvez voir diverses html et markdown options de génération de sortie à (ou regarder ici pour un exemple de markdown sur SO):

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

le TravisCI script qui fait toute l'automatisation est ce simple .travis.yml fichier:

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 : Le hypercore protocole est l'un des spécifications de base de la Dat Projet écosystème de modules pour la création décentralisée peer-to-peer. J'ai utilisé leur .proto fichier pour illustrer les concepts )

Doxygen prend en charge les filtres d'entrée, qui vous permettent de transformer le code en quelque chose que doxygen comprend. L'écriture d'un tel filtre pour transformer L'IDL Protobuf en code C++ (par exemple) vous permettrait d'utiliser la pleine puissance de Doxygen .proto fichiers. Voir le point 12 de la Doxygen FAQ .

j'ai fait quelque chose de similaire pour CMake, le filtre d'entrée transforme simplement les macros CMake et les fonctions en déclarations de fonction C. Vous pouvez trouver c'est ici .

Le fil est vieux, mais la question semble toujours pertinente. J'ai eu de très bons résultats avec Doxygen + proto2cpp . proto2cpp fonctionne comme un filtre d'entrée pour Doxygen.

depuis le .le fichier proto est surtout une simple déclaration, je trouve généralement que le fichier source avec des commentaires en ligne est une documentation simple et efficace.

Dans Protobuf 2.5 "//" les commentaires que vous mettez dans votre .les fichiers proto font en fait partie du code source java généré comme le commente Javadoc. Plus précisément, le compilateur de protocole prendra votre " / / "commentaires comme ceci:

// 
// Message level comments
message myMsg {

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

ira dans vos fichiers java source générés. Pour une raison quelconque, les protocoles contiennent les commentaires Javadoc dans les étiquettes <pre> . Mais dans l'ensemble c'est une belle nouvelle fonctionnalité v2.5.

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

Auto-décrire des Messages

Les tampons du protocole

ne contiennent pas de description de leur propre type. Ainsi, seulement un message brut sans le correspondant .fichier proto en définissant son type, il est difficile d'extraire des données utiles.

toutefois, il convient de noter que le contenu d'un .le fichier proto peut lui-même être représenté à l'aide de tampons de protocole. Fichier src/google/protobuf/descripteur.proto dans le paquet de code source définit les types de messages concernés. protocole peut produire un FileDescriptorSet-qui représente un ensemble de .proto files – en utilisant le -- descriptor_set_out option. Avec ceci, vous pourriez définir un message de protocole auto-description comme ceci:

message SelfDescribingMessage { // Définition de .les fichiers proto qui définissent type. requis FileDescriptorSet proto_files = 1;

/ / nom du type de message. Doit être défini par l'un des fichiers // proto_files. chaîne de caractères requise type_name = 2;

/ / les données du message. nombre requis d'octets message_data = 3;}

en utilisant des classes comme DynamicMessage (disponible en C++ et Java), vous peut alors écrire des outils qui peuvent manipuler des messages Autodescripteurs.

Tout ce qui a dit, la raison pour laquelle ce la fonctionnalité n'est pas incluse dans la bibliothèque de protocole Buffer est parce que nous n'avons jamais eu d'utilisation pour elle à l'intérieur de Google.