Sync hybrid: clean up and fix docs

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/sync/Sync.java

@@ -81,22 +81,23 @@ public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCreden
     }
 
     /**
-     * Starts building a {@link SyncHybridBuilder}, a client/server hybrid typically used for embedded cluster setups.
-     * <p/>
+     * Starts building a {@link SyncHybrid}, a client/server hybrid typically used for embedded cluster setups.
+     * <p>
      * Unlike {@link #client(BoxStore, String, SyncCredentials)} and {@link #server(BoxStore, String, SyncCredentials)},
-     * you cannot pass in an already built store. Instead, you must pass in the store builder.
-     * The store will be created internally when calling this method.
-     * <p/>
-     * As this is a hybrid, you can configure client and server aspects using the {@link SyncHybridBuilder}.
+     * the client Store is not built before. Instead, a Store builder must be passed. The client and server Store will
+     * be built internally when calling this method.
+     * <p>
+     * To configure client and server use the methods on {@link SyncHybridBuilder}.
      *
-     * @param storeBuilder the BoxStoreBuilder to use for building the main store.
+     * @param storeBuilder The {@link BoxStoreBuilder} to use for building the client store.
      * @param url The URL of the Sync server on which the Sync protocol is exposed. This is typically a WebSockets URL
      * starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
      * {@code ws://0.0.0.0:9999}.
-     * @param authenticatorCredentials A list of enabled authentication methods available to Sync clients. Additional
-     * authenticator credentials can be supplied using the builder. For the embedded server, currently only
-     * {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none} are supported.
-     * @return an instance of SyncHybridBuilder.
+     * @param authenticatorCredentials An authentication method available to Sync clients and peers. The client of the
+     * hybrid is pre-configured with them. Additional credentials can be supplied using the client and server builder of
+     * the returned builder. For the embedded server, currently only {@link SyncCredentials#sharedSecret} and
+     * {@link SyncCredentials#none} are supported.
+     * @return An instance of {@link SyncHybridBuilder}.
      */
     public static SyncHybridBuilder hybrid(BoxStoreBuilder storeBuilder, String url,
                                            SyncCredentials authenticatorCredentials) {

objectbox-java/src/main/java/io/objectbox/sync/SyncHybrid.java

@@ -22,13 +22,14 @@
 import io.objectbox.sync.server.SyncServer;
 
 /**
- * The SyncHybrid combines the functionality of a Sync Client and a Sync Server.
+ * Combines the functionality of a Sync client and a Sync server.
+ * <p>
  * It is typically used in local cluster setups, in which a "hybrid" functions as a client & cluster peer (server).
- * <p/>
- * Call {@link #getStore()} to retrieve the store.
- * To set sync listeners use the {@link SyncClient} that is available from {@link #getClient()}.
- * <p/>
- * This class implements the Closeable interface, ensuring that resources are cleaned up properly.
+ * <p>
+ * Call {@link #getStore()} to retrieve the store. To set sync listeners use the {@link SyncClient} that is available
+ * from {@link #getClient()}.
+ * <p>
+ * This class implements the {@link Closeable} interface, ensuring that resources are cleaned up properly.
  */
 public final class SyncHybrid implements Closeable {
     private BoxStore store;
@@ -48,39 +49,50 @@ public BoxStore getStore() {
     }
 
     /**
-     * Typically only used to set sync listeners.
-     * <p/>
-     * Note: you should not directly call start(), stop(), close() on the {@link SyncClient} directly.
-     * Instead, call {@link #stop()} or {@link #close()} on this instance (it is already started during creation).
+     * Returns the {@link SyncClient} of this hybrid, typically only to set Sync listeners.
+     * <p>
+     * Note: do not stop or close the client directly. Instead, use the {@link #stop()} and {@link #close()} methods of
+     * this hybrid.
      */
     public SyncClient getClient() {
         return client;
     }
 
     /**
-     * Typically, you won't need access to the SyncServer.
-     * It is still exposed for advanced use cases if you know what you are doing.
-     * <p/>
-     * Note: you should not directly call start(), stop(), close() on the {@link SyncServer} directly.
-     * Instead, call {@link #stop()} or {@link #close()} on this instance (it is already started during creation).
+     * Returns the {@link SyncServer} of this hybrid.
+     * <p>
+     * Typically, the server should not be touched. Yet, it is still exposed for advanced use cases.
+     * <p>
+     * Note: do not stop or close the server directly. Instead, use the {@link #stop()} and {@link #close()} methods of
+     * this hybrid.
      */
     public SyncServer getServer() {
         return server;
     }
 
+    /**
+     * Stops the client and server.
+     */
     public void stop() {
         client.stop();
         server.stop();
     }
 
+    /**
+     * Closes and cleans up all resources used by this Sync hybrid.
+     * <p>
+     * It can no longer be used afterward, build a new one instead.
+     * <p>
+     * Does nothing if this has already been closed.
+     */
     @Override
     public void close() {
         // Clear reference to boxStore but do not close it (same behavior as SyncClient and SyncServer)
         store = null;
         client.close();
         server.close();
         if (storeServer != null) {
-            storeServer.close();  // The server store is "internal", so we can close it
+            storeServer.close(); // The server store is "internal", so can safely close it
             storeServer = null;
         }
     }

objectbox-java/src/main/java/io/objectbox/sync/SyncHybridBuilder.java

@@ -24,7 +24,8 @@
 import io.objectbox.sync.server.SyncServerBuilder;
 
 /**
- * Allows to configure the client and server setup to build a {@link SyncHybrid}.
+ * Builder for a Sync client and server hybrid setup, a {@link SyncHybrid}.
+ * <p>
  * To change the server/cluster configuration, call {@link #serverBuilder()}, and for the client configuration
  * {@link #clientBuilder()}.
  */
@@ -50,26 +51,27 @@ public final class SyncHybridBuilder {
     }
 
     /**
-     * Allows to customize client options of the hybrid.
+     * Returns the builder of the client of the hybrid for additional configuration.
      */
     public SyncBuilder clientBuilder() {
         return clientBuilder;
     }
 
     /**
-     * Allows to customize server options of the hybrid.
+     * Returns the builder of the server of the hybrid for additional configuration.
      */
     public SyncServerBuilder serverBuilder() {
         return serverBuilder;
     }
 
     /**
-     * Builds, starts and returns a SyncHybrid.
-     * Note that building and started must be done in one go for hybrids to ensure the correct sequence.
+     * Builds, starts and returns the hybrid.
+     * <p>
+     * Ensures the correct order of starting the server and client.
      */
     @SuppressWarnings("resource") // User is responsible for closing
     public SyncHybrid buildAndStart() {
-        // Build and start the server first, we may need to get a  port for the client
+        // Build and start the server first to obtain its URL, the port may have been set to 0 and dynamically assigned
         SyncServer server = serverBuilder.buildAndStart();
 
         SyncClient client = clientBuilder