Better document implemented gRPC services #1449
Conversation
|
@armiol Please take a look. When we are done with |
|
@armiol Please take a look on a second iteration. |
There was a problem hiding this comment.
@yevhenii-nadtochii please see my comments.
Let's discuss my comments vocally once you return back to this task.
| * | ||
| * <p>This class is an implementation of a corresponding gRPC service. Hence, public API of this | ||
| * class is dictated by the {@linkplain CommandServiceGrpc generated code}. Despite the fact of its | ||
| * "publicity", it's not meant to be used directly. Use {@link io.spine.client.Client Client} |
There was a problem hiding this comment.
This is not true. It is meant to be used directly. Otherwise, users won't be able to assembly the definitions of services for their gRPC servers at server-side.
Please rephrase.
| // an acknowledgement. The received `Ack` may have one of the following statuses: | ||
| // | ||
| // 1. `Ok` meaning the command is accepted for further processing. | ||
| // 2. `Error` when a technical error occurs on the side of the application. |
There was a problem hiding this comment.
Please be more specific. What is a technical error? What is the "side of the application"? Both client and server make the application as a whole.
| * | ||
| * <pre>Ack post(Command);</pre> | ||
| * | ||
| * <p>But for every service, gRPC generates several clients: blocking, asynchronous, |
There was a problem hiding this comment.
There are two issues with this text.
-
It is pretty much the same for every method which is generated after gRPC. So it would be nice to write it once and "run everywhere" (meaning, reference, not copy).
-
The wording here is a bit harsh. We aren't the authors of gRPC. And for sure we have chosen to use them voluntarily. Therefore, they don't owe us anything. But the impression of this text is that they do.
| // when the permissions of a user who made a request aren't broad enough. | ||
| // | ||
| // In case of internal gRPC errors or issues on a transport layer, an `Ack` would not be | ||
| // received. All errors which occur on the side of gRCP should be handled by the means |
| // | ||
| // In case of internal gRPC errors or issues on a transport layer, an `Ack` would not be | ||
| // received. All errors which occur on the side of gRCP should be handled by the means | ||
| // of the used client stub. |
There was a problem hiding this comment.
It is not "used". Maybe, "chosen", or no word at all.
| // When the command is successfully received by the application, it responds with | ||
| // an acknowledgement. The received `Ack` may have one of the following statuses: | ||
| // | ||
| // 1. `Ok` meaning the command is accepted for further processing. |
| // an acknowledgement. The received `Ack` may have one of the following statuses: | ||
| // | ||
| // 1. `Ok` meaning the command is accepted for further processing. | ||
| // 2. `Error` when a technical error occurs on the side of the application. |
| // | ||
| // 1. `Ok` meaning the command is accepted for further processing. | ||
| // 2. `Error` when a technical error occurs on the side of the application. | ||
| // 3. `Rejection` if no technical error occurred but due to the business rules the command |
This PR brings better documentation for the implemented gRPC services.