Auto-generate protocol documentation from inline comments in schema.proto

[aschrijver]

For my message layer research wrt hypercore-protocol I was referred to the dat network protocol specification.

However, I found README docs to be outdated when looking at current schema.proto To avoid this, now and forever, you could auto-generate the documentation from inline documentation in the .proto file(s) itself.

For example with protoc-gen-doc from this:

• Booking.proto
• Customer.proto
• Vehicle.proto

You'd get outputs like this:

• Markdown
• HTML
• DocBook
• PDF
• JSON

Benefits:

• specification and documentation maintained in one place
• specification and documentation never out-of-sync
• documentation in multiple output formats

[aschrijver]

Demonstration + documentation of auto-generation options using TravisCI

• https://github.com/aschrijver/hypercore-protocol/tree/feature/document-generator

[aschrijver]

Status: The owner of protoc-gen-doc has completely rewritten the project to Go and using docker. I am working with him to get the issues out of it and create nice markdown documentation layout.

• See: https://github.com/aschrijver/hypercore-protocol/tree/feature/document-generator-new