Proposal: support code samples for messages and methods

[Martin91]

Background

Some documents provide not only parameter structures but also code samples, however, protoc-gen-doc doesn't support the latter function. Like Mermade/widdershins, it supports code samples generation, which makes it more convenient for mkdocs and slate-docs users. We are using protoc-gen-doc to generate documents for external developers, and they will appreciate that if we can add some code samples to the documentation.

Proposal

We can implement a new template function sample to support generating code for specified messages and methods, and the generated markdown document will be like this:

I am implementing it in my fork version, you can view it from: https://github.com/pseudomuto/protoc-gen-doc/compare/master...HackerPie:support-code-sample?expand=1

I have implemented the way to generate samples for messages, before I decide to submit a PR, I wonder if it is a useful function.

[Martin91]

Additionally, we can also consider supporting customized samples in the comments:

message Greet {
  // @sample "a customized sample instead of default one"
  string name = 1;
  // this field will keep using default sample, that is, "string"
  string message = 2;
}

and it will generate:

{
  "name": "a customized sample instead of default one",
  "message": "string"
}

[seeflood]

Cool ! I need this feature !