PBJ lacks a plugin interface similar to protoC (for good reason), and also does not have native documentation generation (provided by plugins for protoC). Javadoc-style document generation and the markdown document format are both highly useful and well understood by software engineers.
Solution
We believe that PBJ should incorporate (either directly or as a separate process) document generation based on the golang protoC plugin protoc-gen-doc, specifically the markdown producing mode. This process should work as correctly as possible and, at minimum, produce results at least as readable as what is produced using protoc-gen-doc with the attached modified template file modified_md.tmpl (which fixes a feature gap in the field documentation).
Alternatives
Continue to produce documentation using protoC and protoc-gen-doc. This is functional, but requires manual steps and is not nearly as clean as PBJ generating the documents. The current approach also suffers from some limitations due to the way protoc-gen-doc is designed, PBJ could be much better in this regard.
Problem
PBJ lacks a plugin interface similar to protoC (for good reason), and also does not have native documentation generation (provided by plugins for protoC). Javadoc-style document generation and the markdown document format are both highly useful and well understood by software engineers.
Solution
We believe that PBJ should incorporate (either directly or as a separate process) document generation based on the golang protoC plugin
protoc-gen-doc, specifically the markdown producing mode. This process should work as correctly as possible and, at minimum, produce results at least as readable as what is produced using protoc-gen-doc with the attached modified template file modified_md.tmpl (which fixes a feature gap in the field documentation).Alternatives
Continue to produce documentation using protoC and protoc-gen-doc. This is functional, but requires manual steps and is not nearly as clean as PBJ generating the documents. The current approach also suffers from some limitations due to the way protoc-gen-doc is designed, PBJ could be much better in this regard.