有没有人知道使用.proto源文件生成Google Protobuf文档的好工具?
一个开源的protobuf插件,可以从proto文件生成DocBook和PDF。
http://code.google.com/p/protoc-gen-docbook/
免责声明:我是该插件的作者。
除了askldjd的答案之外,我想在https://github.com/estan/protoc-gen-doc指出我自己的工具。它也是一个协议缓冲区编译器插件,但可以开箱即用生成HTML,MarkDown或DocBook。它也可以使用Mustache模板进行自定义,以生成您喜欢的任何基于文本的格式。
文档注释使用/** ... */
或/// ...
编写。
[更新:2017年8月。适应完整的Go重写protoc-gen-bug,目前1.0.0-rc
]
由@estan创建的protoc-doc-gen
(另请参阅his earlier answer)提供了一种以html,json,markdown,pdf和其他格式生成文档的简便方法。
我还应该提到一些额外的事情:
protoc-doc-gen
的维护者,但是pseudomuto是protoc-gen-doc
已在Go中完全重写,现在使用Docker进行生成(而不是apt-get
)存储库现在在这里:https://github.com/pseudomuto/protoc-gen-doc
为了演示第二点,我创建了一个示例存储库,以一种很好的格式自动生成Dat Project Hypercore协议文档。
您可以查看各种html
和markdown
输出生成选项(或者查看here以获取SO上的降价示例):
执行所有自动化的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
文件来演示概念)
Doxygen支持所谓的输入过滤器,它允许您将代码转换为doxygen理解的内容。编写这样的过滤器以将Protobuf IDL转换为C ++代码(例如)将允许您在.proto文件中使用Doxygen的全部功能。见Doxygen FAQ的第12项。
我为CMake做了类似的事情,输入过滤器只是将CMake宏和函数转换为C函数声明。你可以找到它here。
在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中一个不错的新功能。
由于.proto文件大多只是声明,我通常会发现带有内联注释的源文件是简单而有效的文档。
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中的一个文件定义。必需的字符串type_name = 2;
//消息数据必需字节message_data = 3; }
通过使用DynamicMessage(可在C ++和Java中使用)这样的类,您可以编写可以操作SelfDescribingMessages的工具。
总而言之,这个功能未包含在协议缓冲库中的原因是因为我们从未在Google内部使用它。