Add docs to SchemaException, other docs changes, match with Dart.

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/BoxStoreBuilder.java

@@ -36,6 +36,7 @@
 import io.objectbox.exception.DbException;
 import io.objectbox.exception.DbFullException;
 import io.objectbox.exception.DbMaxDataSizeExceededException;
+import io.objectbox.exception.DbMaxReadersExceededException;
 import io.objectbox.flatbuffers.FlatBufferBuilder;
 import io.objectbox.ideasonly.ModelUpdate;
 import io.objectbox.model.FlatStoreOptions;
@@ -291,18 +292,18 @@ public BoxStoreBuilder fileMode(int mode) {
     }
 
     /**
-     * Sets the maximum number of concurrent readers. For most applications, the default is fine (~ 126 readers).
+     * Sets the maximum number of concurrent readers. For most applications, the default is fine (about 126 readers).
      * <p>
-     * A "reader" is short for a thread involved in a read transaction.
+     * A "reader" is short for a thread involved in a read transaction. If the maximum is exceeded the store throws
+     * {@link DbMaxReadersExceededException}. In this case check that your code only uses a reasonable amount of
+     * threads.
      * <p>
-     * If you hit {@link io.objectbox.exception.DbMaxReadersExceededException}, you should first worry about the
-     * amount of threads you are using.
      * For highly concurrent setups (e.g. you are using ObjectBox on the server side) it may make sense to increase the
      * number.
      * <p>
      * Note: Each thread that performed a read transaction and is still alive holds on to a reader slot.
      * These slots only get vacated when the thread ends. Thus, be mindful with the number of active threads.
-     * Alternatively, you can opt to try the experimental noReaderThreadLocals option flag.
+     * Alternatively, you can try the experimental {@link #noReaderThreadLocals()} option flag.
      */
     public BoxStoreBuilder maxReaders(int maxReaders) {
         this.maxReaders = maxReaders;
@@ -460,8 +461,8 @@ public BoxStoreBuilder debugRelations() {
     /**
      * For massive concurrent setups (app is using a lot of threads), you can enable automatic retries for queries.
      * This can resolve situations in which resources are getting sparse (e.g.
-     * {@link io.objectbox.exception.DbMaxReadersExceededException} or other variations of
-     * {@link io.objectbox.exception.DbException} are thrown during query execution).
+     * {@link DbMaxReadersExceededException} or other variations of
+     * {@link DbException} are thrown during query execution).
      *
      * @param queryAttempts number of attempts a query find operation will be executed before failing.
      * Recommended values are in the range of 2 to 5, e.g. a value of 3 as a starting point.

objectbox-java/src/main/java/io/objectbox/exception/DbMaxReadersExceededException.java

@@ -21,9 +21,9 @@
 
 /**
  * Thrown when the maximum of readers (read transactions) was exceeded.
- * Verify that you run a reasonable amount of threads only.
+ * Verify that your code only uses a reasonable amount of threads.
  * <p>
- * If you intend to work with a very high number of threads (&gt;100), consider increasing the number of maximum readers
+ * If a very high number of threads (&gt;100) needs to be used, consider increasing the number of maximum readers
  * using {@link BoxStoreBuilder#maxReaders(int)} and enabling query retries using
  * {@link BoxStoreBuilder#queryAttempts(int)}.
  * <p>

objectbox-java/src/main/java/io/objectbox/exception/DbSchemaException.java

@@ -16,6 +16,15 @@
 
 package io.objectbox.exception;
 
+/**
+ * Thrown when there is an error with the data schema (data model).
+ * <p>
+ * Typically, there is a conflict between the data model defined in your code (using {@link io.objectbox.annotation.Entity @Entity}
+ * classes) and the data model of the existing database file.
+ * <p>
+ * Read the <a href="https://docs.objectbox.io/advanced/meta-model-ids-and-uids#resolving-meta-model-conflicts">meta model docs</a>
+ * on why this can happen and how to resolve such conflicts.
+ */
 public class DbSchemaException extends DbException {
     public DbSchemaException(String message) {
         super(message);

objectbox-java/src/main/java/io/objectbox/exception/DbShutdownException.java

@@ -17,10 +17,10 @@
 package io.objectbox.exception;
 
 /**
- * Thrown when an error occurred that requires the DB to shutdown.
- * This may be an I/O error for example.
- * Regular operations won't be possible anymore.
- * To handle that situation you could exit the app or try to reopen the store.
+ * Thrown when an error occurred that requires the store to be closed.
+ * <p>
+ * This may be an I/O error. Regular operations won't be possible.
+ * To handle this exit the app or try to reopen the store.
  */
 public class DbShutdownException extends DbException {
     public DbShutdownException(String message) {

objectbox-java/src/main/java/io/objectbox/exception/FileCorruptException.java

@@ -15,7 +15,14 @@
  */
 package io.objectbox.exception;
 
-/** Errors were detected in a file, e.g. illegal values or structural inconsistencies. */
+import io.objectbox.BoxStoreBuilder;
+
+/**
+ * Errors were detected in a database file, e.g. illegal values or structural inconsistencies.
+ * <p>
+ * It may be possible to re-open the store with {@link BoxStoreBuilder#usePreviousCommit()} to restore
+ * to a working state.
+ */
 public class FileCorruptException extends DbException {
     public FileCorruptException(String message) {
         super(message);

objectbox-java/src/main/java/io/objectbox/exception/PagesCorruptException.java

@@ -15,7 +15,9 @@
  */
 package io.objectbox.exception;
 
-/** Errors were detected in a file related to pages, e.g. illegal values or structural inconsistencies. */
+/**
+ * Errors related to pages were detected in a database file, e.g. bad page refs outside of the file.
+ */
 public class PagesCorruptException extends FileCorruptException {
     public PagesCorruptException(String message) {
         super(message);