Documentation Generator for Google Protocol Buffers

As part of my summer job these past two summers I’ve had to work quite a lot with Protocol Buffers, Google’s data interchange format. The Protocol Buffers compiler (protoc) takes message definitions like

message Person {
  required int32 id = 1;
  required string name = 2;
  optional string email = 3;

and generates C++, Java or Python code for message manipulation and (de)serialization. Protocol Buffers has been around for a while, and nowadays there are cooler kids on the block like Cap’n Proto and MessagePack. But Protocol Buffers remains a quite popular serialization format, and it is widely used.

One thing that always bothered me is that Protocol Buffers has no built-in support for documentation comments, something like Doxygen or JavaDoc. I found one third party tool, but it could only generate DocBook and was quite Windows-centric.

Long story short, I wrote my own little tool. It’s quite simple, but supports /// or /** */ documentation comments for messages, fields, enums and enum values within Protocol Buffer message definitions. Like this:

 * A Person is something with a personality.
 * Most of the time...
message Person {
  required int32 id = 1;    /// How impersonal...
  required string name = 2; /// Yay!

  /** Optional? In this day and age?! */
  optional string email = 3;

The tool works as a plugin for the protoc compiler. It runs on Linux, Windows and Mac OS X and can output HTML, Markdown or DocBook documentation natively, with support for custom output formats through Mustache templates. See the GitHub repo for more examples and sample output.

I hope someone else finds it useful :)