[bisq-network/bisq] Modify .proto file comments to be parsed by bisq-grpc-api-doc (PR #6042)

[Stan]

This change should be low-risk, consisting mostly of adding some new comments, and deleting old 

                ///////////////////// Banner Style /////////////////////

comments from .proto files (categorizing groups of protobuf message definitions).  The [gRPC API reference doc generator](https://github.com/ghubstan/bisq-grpc-api-doc) 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 `deprecated` fields inside `oneof message { }` blocks.  I tried to use the `reserved` keyword 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 the `reserved` keyword inside `oneof message` blocks.  Luckily, the gRPC services do not directly depend on `pb.proto` message definitions such as `PersistableEnvelope`, 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](https://github.com/ghubstan/bisq-grpc-api-doc) before producing [Slate](https://github.com/slatedocs/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](https://ghubstan.github.io/slate) every time I submit comment changes to .proto files.  
	
Based on 'master'
You can view, comment on, or merge this pull request online at:

  https://github.com/bisq-network/bisq/pull/6042

-- Commit Summary --

  * Remove banner style comments from pb.proto
  * Add license comment
  * Begin commenting grpc.proto for bisq-grpc-api-doc

-- File Changes --

    M proto/src/main/proto/grpc.proto (165)
    M proto/src/main/proto/pb.proto (230)

-- Patch Links --

https://github.com/bisq-network/bisq/pull/6042.patch
https://github.com/bisq-network/bisq/pull/6042.diff

-- 
Reply to this email directly or view it on GitHub:
https://github.com/bisq-network/bisq/pull/6042
You are receiving this because you are subscribed to this thread.

Message ID: <bisq-network/bisq/pull/6042 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/bisq-github/attachments/20220212/d00389df/attachment.htm>