Question

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

Answer 1

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

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

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

Answer 2

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

文档评论使用/** ... */或/// ...。

撰写

Answer 3

[更新：2017年8月。适应完整的Go重写protoc-gen-bug，目前1.0.0-rc]

由@estan创建的protoc-doc-gen（另请参阅his earlier answer）提供了一种以html，json，markdown，pdf和其他格式生成文档的简便方法。

我应该提及其他一些事项：

estan不再是protoc-doc-gen的维护者，但pseudomuto
与我在各个页面上阅读的内容相反，可以在评论中使用丰富的内联格式（粗体/斜体，链接，代码段等）
protoc-gen-doc已在Go中完全重写，现在使用Docker进行生成（而不是apt-get）

存储库现在位于：https://github.com/pseudomuto/protoc-gen-doc

为了演示第二点，我创建了一个示例存储库，以便以一种不错的格式自动生成Dat Project Hypercore协议文档。

您可以在（或here查看SO上的降价示例）查看各种html和markdown输出生成选项：

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

Answer 4

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

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

Answer 5

线程陈旧，但问题似乎仍然相关。 doxygen + proto2cpp我的成绩非常好。 proto2cpp作为doxygen的输入过滤器。

Answer 6

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

// 
// Message level comments
message myMsg {

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

将进入生成的java源文件。出于某种原因，protoc在<pre>标记中包含了Javadoc注释。但总而言之，它在v2.5中是一个不错的新功能。

Answer 7

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

Answer 8

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

自我描述的消息

协议缓冲区不包含其自身类型的描述。从而，   仅给出没有相应.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的工具。

所有这些都说明了这个功能没有包含在内的原因   协议缓冲库是因为我们从来没有使用它   在Google内部。

生成Protobuf文档？

8 个答案: