生成Protobuf文檔？

Question

有誰知道使用.proto源文件生成Google Protobuf文檔的好工具嗎？

Answer 1

Doxygen支持所謂的輸入過濾器，它允許您將代碼轉換爲doxygen理解的內容。編寫用於將Protobuf IDL轉換爲C++代碼（例如）的過濾器將允許您在.proto文件中使用Doxygen的全部功能。參見Doxygen FAQ的第12項。

我爲CMake做了類似的事情，輸入過濾器只是將CMake宏和函數轉換爲C函數聲明。你可以找到它here。

Answer 2

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的工具。

所有這一切說，該功能不包括在 協議緩衝區庫是因爲我們從來沒有使用它在谷歌內部 。

Answer 3

由於.proto文件大多隻是聲明，我通常會發現帶有內聯註釋的源文件是直接有效的文檔。

Answer 4

一個開源的protobuf插件，可以從proto文件生成DocBook和PDF。

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

免責聲明：我是插件的作者。

Answer 5

在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中的一個不錯的新功能。

Answer 6

線程已舊，但問題似乎仍然相關。我用Doxygen + proto2cpp獲得了非常好的結果。 proto2cpp作爲Doxygen的輸入過濾器。

Answer 7

除了askldjd的回答，我想指出我自己的工具https://github.com/estan/protoc-gen-doc。它也是一個協議緩衝區編譯器插件，但可以生成HTML，MarkDown或DocBook。它也可以使用Mustache模板進行自定義，以生成您喜歡的任何基於文本的格式。

文檔意見採用/** ... */或/// ...撰寫。

Answer 8

[更新：2017年八月適應於protoc-GEN-錯誤的精力充沛的重寫，目前1.0.0-rc]

的protoc-doc-gen，通過@estan創建（見his earlier answer）提供了一個很好的和簡單的方法以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多核協議文檔。

您可以查看各種html和markdown輸出生成選項（或查找here對SO減價爲例）：

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