Documentation 生成Protobuf文档？

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

Doxygen支持所谓的输入过滤器，它允许您将代码转换为Doxygen理解的内容。编写这样一个过滤器，将原BoFIDIDL转换成C++代码（例如），可以让您使用DoXGEIN .PROTO文件的全部电源。见本报告第12项

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

自我描述信息

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

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

message selfdescripingmessage{//定义 类型.required FileDescriptorSet proto_files=1

//消息类型的名称。必须由中的一个文件定义 //proto_文件。必需的字符串类型_name=2

//消息数据。所需字节消息\u data=3；}

使用动态消息（C++和java中可用的）类 然后可以编写能够处理自描述消息的工具

尽管如此，该功能未包含在 协议缓冲库是因为我们从未使用过它 谷歌内部

---

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

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

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

在Protobuf 2.5中，您在.proto文件中添加的“/”注释实际上会作为Javadoc注释添加到生成的java源代码中。更具体地说，protoc编译器将接受您的“/”注释，如下所示：

// 
// Message level comments
message myMsg {

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

---

将进入生成的java源文件。出于某种原因，protoc将Javadoc注释封装在

标记中。但总的来说，这是v2.5中一个不错的新特性。

线程已经过时，但问题似乎仍然相关。我在+方面取得了非常好的成绩。proto2cpp是一个用于doxygen的输入过滤器。

除了askldjd的答案之外，我想在这里指出我自己的工具。它也是一个协议缓冲区编译器插件，但可以直接生成HTML、MarkDown或DocBook。还可以使用小胡子模板对其进行自定义，以生成您喜欢的任何基于文本的格式

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

---

文档注释是使用

/***/或
//…
[更新：2017年8月。适应protoc gen bug的全面重写，目前
1.0.0-rc
]

@estan创建的
protoc doc gen
（另请参见）提供了一种以html、json、markdown、pdf和其他格式生成文档的好方法

我还应该提到其他一些事情：

不再是protoc doc gen的维护者，而是
与我在不同页面上读到的内容不同，在注释中可以使用丰富的内联格式（粗体/斜体、链接、代码段等）
protoc gen doc
已在Go中完全重写，现在使用Docker生成（而不是
apt get
）
存储库现在位于此处：

为了演示第二点，我创建了一个示例存储库，以一种良好的格式自动生成Hypercore协议文档

您可以在以下位置查看各种
html
和
markdown
输出生成选项（或查找markdown示例）：




执行所有自动化操作的脚本是这个简单的
.travis.yml
文件：

（PS：协议是模块生态系统的核心规范之一，用于创建分散的对等应用程序。我使用他们的
.proto
文件演示概念）
上次我检查时（承认是在不久前），“protoc”工具没有保留任何注释，因此，任何基于使用序列化描述符的操作都会很困难-它可能必须是一个自定义解析器。看看这个线程，这是关于将数据类型定义与实际数据一起传输的，它没有说明任何关于文档的内容。看起来不错。我将试一试。proto文件仅对开发人员有效。它可能不适用于技术人员较少的人员。我无法将下载文件中提供的示例用于Doxygen v1.8.9.1和proto2cpp v0.5-beta。如果我打开文件
html/index.html
，我看不到任何文档。我已经启用了日志记录并粘贴了生成的
proto2cpp.log
文件的输出。关于Doxygen中的过滤有什么变化吗？你知道怎么修吗？或者我对这个项目有错误的期望吗？它在v1.8.1.1中的工作与预期一样，尽管我在“Doxgen”的变更日志中找不到关于输入过滤的根本性更改。