search

pseudomuto / protoc-gen-doc

Documentation generator plugin for Google Protocol Buffers
MIT License
2.64k stars 464 forks source link

Add options and option extensions #376

Closed htdvisser closed 5 years ago

htdvisser commented 5 years ago

ping @pseudomuto

This pull request builds on top of https://github.com/pseudomuto/protokit/pull/2 and https://github.com/pseudomuto/protokit/pull/4 to add support for options and extended options in files, services, methods, enums, enum values, messages and fields.

It supports two builtin protobuf options:

and three external extensions:

Notes

Right now for validator.field we use reflection to transform the field validation rules, but it could be nice to generate the code for that from vendor/github.com/mwitkow/go-proto-validators/validator.proto.

I'm currently importing github.com/pseudomuto/protokit/fixtures/extend.proto, maybe it's cleaner to copy it.

rogchap commented 5 years ago

Seems like this has been forgotten? The main work is now merged in pseudomuto/protokit @htdvisser @pseudomuto

htdvisser commented 5 years ago

It's not forgotten, I see it every time when I click on "Pull Requests" in Github's top bar :wink:

This PR is just waiting for @pseudomuto, and I suspect he's been a bit busy. From his Github activity I suspect that he just returned from a holiday, so maybe he'll find time for it soon.

Everything is basically done, so moving forward, we need to:

  1. Tag a new version of protokit (@pseudomuto)
  2. Update Gopkg.toml/Gopkg.lock in this PR (@htdvisser)
  3. Review this PR (@pseudomuto)
  4. Fix things that came out of review (@htdvisser)
  5. Merge the PR (@pseudomuto)
  6. Possibly tag a new version of protoc-gen-doc (@pseudomuto)
igrayson commented 5 years ago

The ability to emit field/service/method/enum options in json output would be fantastically useful to us (currently using a forked protobuf.js to achieve this). Looking forward to progress!

pseudomuto commented 5 years ago

My apologies for the long-delayed response here. Between vacation, conferences, and work I haven't had enough free time to review this.

Good news is, I've got time this week. I'll make sure I've got this reviewed by the end of the week.

htdvisser commented 5 years ago

It didn't look like @pseudomuto reviewed this yet, so I took the liberty of adding support for the validate.rules option from github.com/lyft/protoc-gen-validate as well.

htdvisser commented 5 years ago

merge

pseudomuto commented 5 years ago

Released! - https://github.com/pseudomuto/protoc-gen-doc/releases/tag/v1.3.0

Thanks again for the PR @htdvisser!

rogchap commented 5 years ago

This is a great addition thanks!... Sadly only outputs for the HTML template. Need to add the changes to the other templates... selfishly the Markdown template :D

htdvisser commented 5 years ago

@rogchap if you want to submit a pull request, feel free to get inspired by the markdown template I wrote for TheThingsNetwork/lorawan-stack