Docs: add for DbDetachedException and Box.attach

Author: greenrobot-team

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2019 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,7 +30,6 @@
 
 import io.objectbox.annotation.Backlink;
 import io.objectbox.annotation.Id;
-import io.objectbox.annotation.apihint.Beta;
 import io.objectbox.annotation.apihint.Experimental;
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.exception.DbException;
@@ -642,7 +641,14 @@ public synchronized EntityInfo<T> getEntityInfo() {
         return entityInfo;
     }
 
-    @Beta
+    /**
+     * Attaches the given object to this.
+     * <p>
+     * This typically should only be used when <a
+     * href="https://docs.objectbox.io/advanced/object-ids#self-assigned-object-ids">manually assigning IDs</a>.
+     *
+     * @param entity The object to attach this to.
+     */
     public void attach(T entity) {
         if (boxStoreField == null) {
             try {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 ObjectBox Ltd. All rights reserved.
+ * Copyright 2017-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,11 +16,23 @@
 
 package io.objectbox.exception;
 
+/**
+ * This exception occurs while working with a {@link io.objectbox.relation.ToMany ToMany} or
+ * {@link io.objectbox.relation.ToOne ToOne} of an object and the object is not attached to a
+ * {@link io.objectbox.Box Box} (technically a {@link io.objectbox.BoxStore BoxStore}).
+ * <p>
+ * If your code uses <a href="https://docs.objectbox.io/advanced/object-ids#self-assigned-object-ids">manually assigned
+ * IDs</a> make sure it takes care of some things that ObjectBox would normally do by itself. This includes
+ * {@link io.objectbox.Box#attach(Object) attaching} the Box to an object before modifying a ToMany.
+ * <p>
+ * Also see the documentation about <a href="https://docs.objectbox.io/relations#updating-relations">Updating
+ * Relations</a> and <a href="https://docs.objectbox.io/advanced/object-ids#self-assigned-object-ids">manually assigned
+ * IDs</a> for details.
+ */
 public class DbDetachedException extends DbException {
 
     public DbDetachedException() {
-        this("Cannot perform this action on a detached entity. " +
-                "Ensure it was loaded by ObjectBox, or attach it manually.");
+        this("Entity must be attached to a Box.");
     }
 
     public DbDetachedException(String message) {