Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add document generation for PBJ #272

Open
jsync-swirlds opened this issue Aug 12, 2024 · 0 comments
Open

Add document generation for PBJ #272

jsync-swirlds opened this issue Aug 12, 2024 · 0 comments
Labels
New Feature A new feature, service, or documentation. Major changes that are not backwards compatible.

Comments

@jsync-swirlds
Copy link
Member

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.

@jsync-swirlds jsync-swirlds added the New Feature A new feature, service, or documentation. Major changes that are not backwards compatible. label Aug 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
New Feature A new feature, service, or documentation. Major changes that are not backwards compatible.
Projects
None yet
Development

No branches or pull requests

1 participant