生成Protobuf文档?
Doxygen支持所谓的输入过滤器,它允许您将代码转换为doxygen理解的内容。编写用于将Protobuf IDL转换为C++代码(例如)的过滤器将允许您在.proto文件中使用Doxygen的全部功能。参见Doxygen FAQ的第12项。
我为CMake做了类似的事情,输入过滤器只是将CMake宏和函数转换为C函数声明。你可以找到它here。
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的工具。
所有这一切说,该功能不包括在 协议缓冲区库是因为我们从来没有使用它在谷歌内部 。
这是关于传输数据类型定义以及实际数据,它没有提及任何关于文档的内容。 – djjeck 2013-01-22 21:07:04
由于.proto文件大多只是声明,我通常会发现带有内联注释的源文件是直接有效的文档。
.proto文件仅适用于开发人员的有效文档。它可能不适合技术人员较少。 – dux2 2013-08-22 08:49:35
在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中的一个不错的新功能。
除了askldjd的回答,我想指出我自己的工具https://github.com/estan/protoc-gen-doc。它也是一个协议缓冲区编译器插件,但可以生成HTML,MarkDown或DocBook。它也可以使用Mustache模板进行自定义,以生成您喜欢的任何基于文本的格式。
文档意见采用/** ... */
或/// ...
撰写。
[更新:2017年八月适应于protoc-GEN-错误的精力充沛的重写,目前1.0.0-rc
]
的protoc-doc-gen
,通过@estan创建(见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多核协议文档。
您可以查看各种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
文件来演示概念)
我最后一次检查(这是前不久前),“protoc”工具没有保留任何注释,所以基于使用序列化描述符的任何东西都是很难 - 它可能必须是一个自定义分析器。 – 2011-02-14 12:45:57
看看这个主题http://www.mail-archive.com/[email protected]/msg02830.html – 2011-02-14 13:54:00