diff --git a/src/main/java/li/cil/oc/api/Machine.java b/src/main/java/li/cil/oc/api/Machine.java
index e69749742..d33ca23db 100644
--- a/src/main/java/li/cil/oc/api/Machine.java
+++ b/src/main/java/li/cil/oc/api/Machine.java
@@ -25,21 +25,58 @@ import java.util.Collections;
  * start calling these methods in the init phase or later.
  */
 public final class Machine {
+    /**
+     * Register an architecture that can be used to create new machines.
+     * <p/>
+     * Note that although registration is optional, it is strongly recommended
+     * to allow {@link #architectures()} to be useful.
+     *
+     * @param architecture the architecture to register.
+     */
     public static void add(Class<? extends Architecture> architecture) {
         if (instance != null) instance.add(architecture);
     }
 
+    /**
+     * A list of all <em>registered</em> architectures.
+     * <p/>
+     * Note that registration is optional, although automatic when calling
+     * {@link #create(li.cil.oc.api.machine.Owner, Class)} with a not yet
+     * registered architecture. What this means is that unless a mod providing
+     * a custom architecture also registers it, you may not see it in this list
+     * until it also created a new machine using that architecture.
+     */
     public static Iterable<Class<? extends Architecture>> architectures() {
         if (instance != null) return instance.architectures();
         return Collections.emptyList();
     }
 
-    public static li.cil.oc.server.component.machine.Machine create(Owner owner, Class<? extends Architecture> architecture) {
+    /**
+     * Creates a new machine using the specified architecture.
+     * <p/>
+     * You are responsible for calling update and save / load functions on the
+     * machine for it to work correctly.
+     *
+     * @param owner        the owner object of the machine, providing context.
+     * @param architecture the architecture to use for running code on the machine.
+     * @return the newly created machine.
+     * @throws IllegalArgumentException if the specified architecture is invalid.
+     */
+    public static li.cil.oc.api.machine.Machine create(Owner owner, Class<? extends Architecture> architecture) {
         if (instance != null) return instance.create(owner, architecture);
         return null;
     }
 
-    public static li.cil.oc.server.component.machine.Machine create(Owner owner) {
+    /**
+     * Creates a new machine using the default architecture (Lua).
+     * <p/>
+     * You are responsible for calling update and save / load functions on the
+     * machine for it to work correctly.
+     *
+     * @param owner the owner object of the machine, providing context.
+     * @return the newly created machine.
+     */
+    public static li.cil.oc.api.machine.Machine create(Owner owner) {
         if (instance != null) return instance.create(owner, LuaArchitecture);
         return null;
     }
diff --git a/src/main/java/li/cil/oc/api/detail/MachineAPI.java b/src/main/java/li/cil/oc/api/detail/MachineAPI.java
index db5d0c875..7a018aa68 100644
--- a/src/main/java/li/cil/oc/api/detail/MachineAPI.java
+++ b/src/main/java/li/cil/oc/api/detail/MachineAPI.java
@@ -1,13 +1,33 @@
 package li.cil.oc.api.detail;
 
 import li.cil.oc.api.machine.Architecture;
+import li.cil.oc.api.machine.Machine;
 import li.cil.oc.api.machine.Owner;
-import li.cil.oc.server.component.machine.Machine;
 
 public interface MachineAPI {
     void add(Class<? extends Architecture> architecture);
 
+    /**
+     * A list of all <em>registered</em> architectures.
+     * <p/>
+     * Note that registration is optional, although automatic when calling
+     * {@link #create(li.cil.oc.api.machine.Owner, Class)} with a not yet
+     * registered architecture. What this means is that unless a mod providing
+     * a custom architecture also registers it, you may not see it in this list
+     * until it also created a new machine using that architecture.
+     */
     Iterable<Class<? extends Architecture>> architectures();
 
+    /**
+     * Creates a new machine using the specified architecture.
+     * <p/>
+     * You are responsible for calling update and save / load functions on the
+     * machine for it to work correctly.
+     *
+     * @param owner        the owner object of the machine, providing context.
+     * @param architecture the architecture to use for running code on the machine.
+     * @return the newly created machine.
+     * @throws IllegalArgumentException if the specified architecture is invalid.
+     */
     Machine create(Owner owner, Class<? extends Architecture> architecture);
 }