hashgraph / hashgraph/pbj

Add document generation for PBJ

Open
#272 0 comments 0 reactions 0 assignees View on GitHub
New Feature
Dominant language
Java
Stars
44
Forks
15
Avg merge
1d 15h
Merged PRs (30d)
12

Description

## 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](https://github.com/user-attachments/files/16590564/modified_md.tmpl.txt) (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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.