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 :)

10 thoughts on “Documentation Generator for Google Protocol Buffers

  1. I’m currently trying out your tool to see if we can use it to generate documentation from some of our protobuf files – it looks pretty great so far! Here’s the problem I’m currently trying to solve: we only want to generate documentation for a subset of messages within our protobuf files. Is there a way to mark some messages so that they are not included in the documentation output? Or is it all or nothing? Thanks for any help!

    1. Hi Melissa, and sorry for the late reply. It’s all or nothing I’m afraid. If you file an issue here I can see if I have time to think out a good mechanism for excluding specific symbols (classes, fields, enums, ..).

Leave a Reply

Your email address will not be published. Required fields are marked *