Modify .proto file comments to be parsed by bisq-grpc-api-doc [#1] #6042
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The bisq-grpc-api-doc generator needs comments spefic to protobuf message definitions, not groups of message defs. This kind of information can be included in the message specific comments. Also changed some existing comments, and added others to suggest a commenting style for .proto message and field defs.
Banner comments were replace by simple service description comments. Rpc methods were commented, some field level comments were moved to to bisq-grpc-api-doc comment conventions.
ghubstan
changed the title
ripcurlx
approved these changes
Feb 14, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This change should be low-risk, consisting mostly of adding some new comments, and deleting old
comments from .proto files (categorizing groups of protobuf message definitions). The gRPC API reference doc generator needs comments specific to each protobuf message definition, not groupings of messages.
The https://github.com/ghubstan/bisq-grpc-api-doc project also needs to be reviewed, and consideration could be given to determine if it should be added to the bisq repo as a new gradle sub-project.
Left as is are
deprecatedfields insideoneof message { }blocks. I tried to use thereservedkeyword in these places to avoid having the api doc generator assume these commented, deprecated fields are describing the not-commented, valid fields below them, but the proto compiler does not allow use of thereservedkeyword insideoneof messageblocks. Luckily, the gRPC services do not directly depend onpb.protomessage definitions such asPersistableEnvelope, and I can get away with leaving those comments alone. A solution to this problem may be needed in the the future.This is the first step in the process of commenting Bisq's .proto files -- to be consumed by the gRPC API Reference generator script bisq-grpc-api-doc before producing Slate style Markdown content to be hosted on GitHub.
Reviews of the generated gRPC API Reference are expected to lead to API changes intended to improve useabiility. The .proto file comment -> reference doc review -> API change cycle will be an iterative process, and backward compatibility will probably be broken.
Note: I will try to remember to update the example API reference every time I submit comment changes to .proto files.
Based on 'master'