Docs: upper-case ObjectBox names, update and expand some.

Author: greenrobot-team

objectbox-java-api/src/main/java/io/objectbox/annotation/BaseEntity.java

@@ -6,8 +6,9 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation for an entity base class.
- * ObjectBox will include properties of an entity super class marked with this annotation.
+ * Marks a class as an ObjectBox Entity super class.
+ * ObjectBox will store properties of this class as part of an Entity that inherits from this class.
+ * See <a href="https://docs.objectbox.io/advanced/entity-inheritance">the Entity Inheritance documentation</a> for details.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)

objectbox-java-api/src/main/java/io/objectbox/annotation/Convert.java

@@ -16,25 +16,29 @@
 
 package io.objectbox.annotation;
 
-import io.objectbox.converter.PropertyConverter;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import io.objectbox.converter.PropertyConverter;
+
 /**
- * Specifies {@link PropertyConverter} for the field to support custom types
+ * Supplies a {@link PropertyConverter converter} to store custom Property types as a supported {@link #dbType()}.
+ * See the <a href="https://docs.objectbox.io/advanced/custom-types">Custom Types documentation</a> for details.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.FIELD)
 public @interface Convert {
-    /** Converter class */
+    /**
+     * The converter class that ObjectBox should use. See {@link PropertyConverter} for implementation guidelines.
+     */
     Class<? extends PropertyConverter> converter();
 
     /**
-     * Class of the DB type the Java property is converted to/from.
-     * This is limited to all java classes which are supported natively by ObjectBox.
+     * The Property type the Java field value is converted to/from.
+     * See the <a href="https://docs.objectbox.io/advanced/custom-types">Custom Types documentation</a> for a list
+     * of supported types.
      */
     Class dbType();
 }

objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java

@@ -22,8 +22,8 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation for entities
- * ObjectBox only persist objects of classes which are marked with this annotation
+ * Marks a class as an ObjectBox Entity.
+ * Allows to obtain a Box for this Entity from BoxStore to persist Objects of this class.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)

objectbox-java-api/src/main/java/io/objectbox/annotation/package-info.java

@@ -16,9 +16,9 @@
 
 /**
  * Annotations to mark a class as an {@link io.objectbox.annotation.Entity @Entity},
- * to specify the {@link io.objectbox.annotation.Id @Id} property,
+ * to specify the {@link io.objectbox.annotation.Id @Id} Property,
  * to create an {@link io.objectbox.annotation.Index @Index} or
- * a {@link io.objectbox.annotation.Transient @Transient} property.
+ * a {@link io.objectbox.annotation.Transient @Transient} Property.
  * <p>
  * For more details look at the documentation of individual classes and
  * <a href="https://docs.objectbox.io/entity-annotations">docs.objectbox.io/entity-annotations</a>.

objectbox-java-api/src/main/java/io/objectbox/converter/package-info.java

@@ -16,7 +16,7 @@
 
 /**
  * For use with {@link io.objectbox.annotation.Convert @Convert}: {@link io.objectbox.converter.PropertyConverter}
- * to convert custom property types.
+ * to convert custom Property types.
  * <p>
  * For more details look at the documentation of individual classes and
  * <a href="https://docs.objectbox.io/advanced/custom-types">docs.objectbox.io/advanced/custom-types</a>.

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

@@ -39,7 +39,7 @@
 import io.objectbox.relation.RelationInfo;
 
 /**
- * A box to store objects of a particular class.
+ * A Box to put and get Objects of a specific Entity class.
  * <p>
  * Thread-safe.
  */

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

@@ -53,8 +53,8 @@
 import io.objectbox.reactive.SubscriptionBuilder;
 
 /**
- * Represents an ObjectBox database and gives you {@link Box}es to get and put Objects of a specific type
- * (see {@link #boxFor(Class)}).
+ * An ObjectBox database that provides {@link Box Boxes} to put and get Objects of a specific Entity class
+ * (see {@link #boxFor(Class)}). To get an instance of this class use {@code MyObjectBox.builder()}.
  */
 @SuppressWarnings({"unused", "UnusedReturnValue", "SameParameterValue", "WeakerAccess"})
 @ThreadSafe

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

@@ -17,7 +17,7 @@
 package io.objectbox;
 
 import com.google.flatbuffers.FlatBufferBuilder;
-import io.objectbox.model.FlatStoreOptions;
+
 import org.greenrobot.essentials.io.IoUtils;
 
 import java.io.BufferedInputStream;
@@ -39,21 +39,20 @@
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.exception.DbException;
 import io.objectbox.ideasonly.ModelUpdate;
+import io.objectbox.model.FlatStoreOptions;
 import io.objectbox.model.ValidateOnOpenMode;
 
 /**
- * Builds a {@link BoxStore} with optional configurations. The class is not initiated directly; use
- * MyObjectBox.builder() to get an instance.
+ * Configures and builds a {@link BoxStore} with reasonable defaults. To get an instance use {@code MyObjectBox.builder()}.
  * <p>
- * Each configuration has reasonable defaults, which you can adjust.
- * For Android, you must pass a Context using {@link #androidContext(Object)}.
+ * On Android, make sure to provide a Context to {@link #androidContext(Object) androidContext(context)}.
  * <p>
- * Configurations you can override:
+ * Some common defaults to override are:
  * <ol>
- * <li>Name/location of DB: use {@link #name(String)}/{@link #baseDirectory}/{@link #androidContext(Object)}
- * OR {@link #directory(File)}(default: name "objectbox)</li>
- * <li>Max DB size: see {@link #maxSizeInKByte} (default: 1 GB)</li>
- * <li>Max readers: see {@link #maxReaders(int)} (default: 126)</li>
+ * <li>Name/location of Store: use either {@link #name(String)}, {@link #baseDirectory(File)},
+ * {@link #androidContext(Object)} or {@link #directory(File)} (default: name "objectbox),</li>
+ * <li>Max DB size: see {@link #maxSizeInKByte(long)} (default: 1024 * 1024 KB = 1 GB),</li>
+ * <li>Max readers: see {@link #maxReaders(int)} (default: 126),</li>
  * </ol>
  */
 public class BoxStoreBuilder {

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

@@ -29,8 +29,10 @@
 import io.objectbox.query.QueryCondition.PropertyCondition.Operation;
 
 /**
- * Meta data describing a property of an ObjectBox entity.
- * Properties are typically used to define query criteria using {@link io.objectbox.query.QueryBuilder}.
+ * Meta data describing a Property of an ObjectBox Entity.
+ * Properties are typically used when defining {@link io.objectbox.query.Query Query} conditions
+ * using {@link io.objectbox.query.QueryBuilder QueryBuilder}.
+ * Access properties using the generated underscore class of an entity (e.g. {@code Example_.id}).
  */
 @SuppressWarnings("WeakerAccess,UnusedReturnValue, unused")
 public class Property<ENTITY> implements Serializable {

objectbox-java/src/main/java/io/objectbox/package-info.java

@@ -22,7 +22,7 @@
  * <li>MyObjectBox: Generated by the Gradle plugin, supplies a {@link io.objectbox.BoxStoreBuilder}
  * to build a BoxStore for your app.</li>
  * <li>{@link io.objectbox.BoxStore}: The database interface, allows to manage Boxes.</li>
- * <li>{@link io.objectbox.Box}: Persists and queries for entities, there is one for each entity.</li>
+ * <li>{@link io.objectbox.Box}: Persists and queries for Objects, there is one for each Entity class.</li>
  * </ul>
  * <p>
  * For more details look at the documentation of individual classes and