Better document implemented gRPC services

client/src/main/proto/spine/client/command_service.proto

@@ -30,18 +30,31 @@ package spine.client;
 import "spine/options.proto";
 
 option (type_url_prefix) = "type.spine.io";
-// We put gRPC-based classes into `grpc` sub-package, which is annotated as `@Internal`
-// to hide implementation details from the public API of the framework.
 option java_package = "io.spine.client.grpc";
 option java_multiple_files = true;
 option java_outer_classname = "CommandServiceProto";
 
 import "spine/core/command.proto";
 import "spine/core/ack.proto";
 
-// A service for sending commands from clients.
+// A service for posting commands to the application backend.
+//
 service CommandService {
 
-    // Request to handle a command.
+    // Posts the given command to the application backend.
+    //
+    // 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.
+    //    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
+    //        should be immediately disqualified from being executed. A typical scenario would be
+    //        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
+    // of the used client stub.
+    //
     rpc Post(core.Command) returns (core.Ack);
 }

server/src/main/java/io/spine/server/CommandService.java

@@ -45,8 +45,13 @@
 import static io.spine.server.bus.Acks.reject;
 
 /**
- * The {@code CommandService} allows client applications to post commands and
- * receive updates from the application backend.
+ * The {@code CommandService} provides a synchronous way to post commands
+ * to the application backend.
+ *
+ * <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}
+ * to post commands to the application.
  */
 public final class CommandService
         extends CommandServiceGrpc.CommandServiceImplBase
@@ -55,7 +60,7 @@ public final class CommandService
     private final ImmutableMap<CommandClass, BoundedContext> commandToContext;
 
     /**
-     * Constructs new instance using the map from a {@code CommandClass} to
+     * Constructs a new instance using the map from a {@code CommandClass} to
      * a {@code BoundedContext} instance which handles the command.
      */
     private CommandService(Map<CommandClass, BoundedContext> map) {
@@ -70,14 +75,41 @@ public static Builder newBuilder() {
         return new Builder();
     }
 
-    /** Builds the service with a single Bounded Context. **/
+    /**
+     * Builds the service with a single Bounded Context.
+     */
     public static CommandService withSingle(BoundedContext context) {
         CommandService result = newBuilder()
                 .add(context)
                 .build();
         return result;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <p>In the original proto definition of this service, this method is unary.
+     * Meaning, for every posted command only a single {@link Ack} is received in response:
+     *
+     * <pre>Ack post(Command);</pre>
+     *
+     * <p>But for every service, gRPC generates several clients: blocking, asynchronous,
+     * {@link com.google.common.util.concurrent.ListenableFuture Future}-based. Each one
+     * has its own signature for this method. And instead of making users to implement three
+     * different signatures of the same method in the
+     * {@linkplain CommandServiceGrpc.CommandServiceImplBase server stub}, they prefer a single
+     * universal method that cover all the cases.
+     *
+     * <p>Although, utilizing of {@link StreamObserver} is quite controversial decision for the
+     * method which does not stream anything. It is still better than implementing this method
+     * three times. For more details on this matter, reference the issue below.
+     *
+     * <p>Please note, all the errors, occurring on the side of the application are still
+     * propagated through the {@linkplain Ack acknowledgement}. They are not passed into the
+     * {@linkplain StreamObserver#onError(Throwable) observer}.
+     *
+     * <p>See issue: <a href="https://github.com/grpc/grpc-java/issues/1474">Improve unary server stub</a>
+     */
     @Override
     public void post(Command request, StreamObserver<Ack> responseObserver) {
         CommandClass commandClass = CommandClass.of(request);