神刀安全网

Documentation generator plugin for Protocol Buffers

protoc-gen-doc

Documentation generator plugin for Protocol Buffers Documentation generator plugin for Protocol Buffers

This is a documentation generator plugin for the Google Protocol Buffers compiler ( protoc ). The plugin can generate HTML, DocBook or Markdown documentation from comments in your .proto files.

Installation

Writing Documentation

Use /** */ or /// comments to document your files. Comments for files go at the very top of the the file. Comments for enumerations, messages and services go before the message, enumeration or service definition. Comments for fields, enum values, extensions and service methods can go either before or after the definition. If a documentation comment begins with @exclude , the corresponding item will be excluded from the generated documentation.

Invoking the Plugin

The plugin is invoked by passing the --doc_out option to the protoc compiler. The option has the following format:

--doc_out=docbook|html|markdown|<TEMPLATE_FILENAME>,<OUT_FILENAME>[,no-exclude]:<OUT_DIR> 

The format may be one of the built-in ones ( docbook , html or markdown ) or the name of a file containing a custom Mustache template. For example, to generate HTML documentation for all .proto files in the proto directory into doc/index.html , type:

protoc --doc_out=html,index.html:doc proto/*.proto 

The plugin executable must be in PATH or specified explicitly using the --plugin option in order for protoc to find it. If you need support for a custom output format, seeCustom Templates. If you just want to customize the look of the HTML output, put your CSS in stylesheet.css next to the output file and it will be picked up. If the optional no-exclude flag is given, all @exclude directives are ignored.

Output Example

With the input .proto files

the plugin gives the output

Look inexamples/Makefile to see how these outputs were built.

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » Documentation generator plugin for Protocol Buffers

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址