生成 Protobuf 文档？

Question

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

- Markus K

---

上次我检查过（虽然是一段时间以前），"protoc"工具不会保留任何注释，因此基于使用序列化描述符的任何内容都很难 - 可能必须是自定义解析器。 - Marc Gravell

请查看此线程 http://www.mail-archive.com/[e-mail]/msg02830.html - Aravind Yarram

Answer 1

【更新】：2017年8月。已适配protoc-gen-bug的完整Go重写版本，当前版本为1.0.0-rc。

由@estan创建的protoc-doc-gen（参见他较早的答案）提供了一种很好而且简单的方法来生成您的文档，包括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 Hypercore Protocol文档。

您可以在此处查看各种 html 和 markdown 输出生成选项（或者在 此处 查看 SO 上的 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文件来演示概念。)

- Arnold Schrijver

Answer 2

一款开源的protobuf插件，可从proto文件中生成DocBook和PDF文档。

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

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

- askldjd

---

有点啰嗦一下，我会说“disclosure”而不是“disclaimer”。 - Tjunkie

Answer 3

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

文档注释使用/** ... */或/// ...编写。

- estan

Answer 4

在Protobuf 2.5版本中，你在.proto文件中加入的"//"注释实际上会被转换为Java源代码生成时的Javadoc注释。具体而言，protoc编译器会将你的"//"注释转化为以下形式：

// 
// Message level comments
message myMsg {

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

这将进入您生成的Java源文件中。由于某种原因，protoc会用<pre>标签括起Javadoc注释。但总的来说，这是v2.5中一个不错的新功能。

- peterh

Answer 5

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

我为CMake做了类似的事情，输入过滤器只需将CMake宏和函数转换为C函数声明即可。您可以在此处找到它。

- Sascha

Answer 6

虽然这个帖子已经很老了，但问题似乎仍然相关。我使用doxygen + proto2cpp取得了非常好的结果。proto2cpp作为doxygen的输入过滤器。

- damjan

---

我无法使用Doxygen v1.8.9.1和proto2cpp v0.5-beta运行下载文件中提供的示例。如果我打开文件html/index.html，我看不到任何文档。我已启用日志记录并粘贴了生成的proto2cpp.log文件的输出在此处。关于Doxygen的过滤是否有所改变？你知道如何解决吗？或者我对这个项目的期望是错误的？ - Florian Wolters

它在v1.8.1.1上按预期工作，尽管我在“Doxgen”的更改日志中找不到关于输入过滤方面的基本更改。 - Florian Wolters

Answer 7

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

- Flwyd

---

.proto文件仅适用于开发人员的有效文档。对于不太技术的员工来说可能不太合适。 - dux2

Answer 8

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

自描述消息

协议缓冲区不包含其自身类型的描述。因此，如果只有原始消息而没有定义其类型的相应.proto文件，则很难提取任何有用的数据。

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

message SelfDescribingMessage { // 定义类型的一组.proto文件。 required FileDescriptorSet proto_files = 1;

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

// 消息数据。 required bytes message_data = 3; }

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

尽管如此，协议缓冲库中未包含此功能的原因是因为我们从未在Google内部使用过它。

- plan9assembler

---

这是关于将数据类型定义与实际数据一起传输，它并没有涉及文档的内容。 - djjeck