生成Protobuf文档？

Question

有谁知道使用.proto源文件生成Google Protobuf文档的好工具吗？

Answer 1

Doxygen支持所谓的输入过滤器，它允许您将代码转换为doxygen理解的内容。编写用于将Protobuf IDL转换为C++代码（例如）的过滤器将允许您在.proto文件中使用Doxygen的全部功能。参见Doxygen FAQ的第12项。

我为CMake做了类似的事情，输入过滤器只是将CMake宏和函数转换为C函数声明。你可以找到它here。

Answer 2

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

自我描述的消息

Protocol Buffers的不包含自己的类型的描述。因此， 只给出一个未定义其类型的对应的.proto文件 的原始消息，因此很难提取任何有用的数据。

但是，请注意，.proto文件的内容本身可以使用协议缓冲区来表示 。源代码包 中的文件 src/google/protobuf/descriptor.proto定义了涉及的消息类型。 protoc可以输出 FileDescriptorSet - 表示一组.proto文件 - 使用 --descriptor_set_out选项。有了这个，你可以定义一个 自描述协议消息，如下所示：

消息SelfDescribingMessage {//定义 类型的.proto文件集。需要FileDescriptorSet proto_files = 1;

//消息类型的名称。必须由 // proto_files中的一个文件定义。必填字符串type_name = 2;

//消息数据。所需字节数message_data = 3; }

通过使用类DynamicMessage（可在C++和Java中使用），您可以编写可以操作SelfDescribingMessages的工具。

所有这一切说，该功能不包括在 协议缓冲区库是因为我们从来没有使用它在谷歌内部 。

Answer 3

由于.proto文件大多只是声明，我通常会发现带有内联注释的源文件是直接有效的文档。

Answer 4

一个开源的protobuf插件，可以从proto文件生成DocBook和PDF。

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

免责声明：我是插件的作者。

Answer 5

在Protobuf 2.5中，您放入.proto文件的“//”注释实际上使其成为Javadoc注释中生成的Java源代码。更具体地说，protoc编译器将采取如下的“//”注释：

// 
// Message level comments 
message myMsg { 

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

将进入您生成的java源文件。由于某种原因，protoc将Javadoc评论标记为<pre>标签。但总而言之，这是v2.5中的一个不错的新功能。

Answer 6

线程已旧，但问题似乎仍然相关。我用Doxygen + proto2cpp获得了非常好的结果。 proto2cpp作为Doxygen的输入过滤器。

Answer 7

除了askldjd的回答，我想指出我自己的工具https://github.com/estan/protoc-gen-doc。它也是一个协议缓冲区编译器插件，但可以生成HTML，MarkDown或DocBook。它也可以使用Mustache模板进行自定义，以生成您喜欢的任何基于文本的格式。

文档意见采用/** ... */或/// ...撰写。

Answer 8

[更新：2017年八月适应于protoc-GEN-错误的精力充沛的重写，目前1.0.0-rc]

的protoc-doc-gen，通过@estan创建（见his earlier answer）提供了一个很好的和简单的方法以html，json，markdown，pdf和其他格式生成您的文档。

有迹象表明，我应该提到的额外的东西数量：

1. estan不再是protoc-doc-gen维护者，但pseudomuto是
2. 相反我读过各种网页它是可能在注释中使用丰富的内联格式（粗体/斜体，链接，代码片段等）
3. protoc-gen-doc已在Go中完全重写，现在使用Docker生成（而不是apt-get）

库是现在的位置：https://github.com/pseudomuto/protoc-gen-doc

为了证明我已经创建了一个例子库到第二个点自动生成一个不错的格式Dat Project多核协议文档。

您可以查看各种html和markdown输出生成选项（或查找here对SO减价为例）：

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

的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文件来演示概念）