[wpilib] Impove Mechanism2D documentation (NFC) (#3584)

wpilibc/src/main/native/include/frc/smartdashboard/Mechanism2d.h

@@ -19,11 +19,12 @@
 namespace frc {
 
 /**
- * Visual 2D representation of arms, elevators, and general mechanisms; through
+ * Visual 2D representation of arms, elevators, and general mechanisms through
  * a node-based API.
  *
- * A Mechanism2d object is published and contains at least one root node. Other
- * nodes (such as ligaments) are recursively based on other nodes.
+ * A Mechanism2d object is published and contains at least one root node. A root
+ * is the anchor point of other nodes (such as ligaments). Other nodes are
+ * recursively appended based on other nodes.
  *
  * Except for the Mechanism2d container object, none of the objects should be
  * passed or interacted with by value! Obtain pointers from factory methods such
@@ -42,6 +43,9 @@ class Mechanism2d : public nt::NTSendable,
   /**
    * Create a new Mechanism2d with the given dimensions and background color.
    *
+   * The dimensions represent the canvas that all the nodes are drawn on. The
+   * default color is dark blue.
+   *
    * @param width the width
    * @param height the height
    */

wpilibc/src/main/native/include/frc/smartdashboard/MechanismLigament2d.h

@@ -18,6 +18,9 @@ namespace frc {
 /**
  * Ligament node on a Mechanism2d.
  *
+ * A ligament can have its length changed (like an elevator) or angle changed,
+ * like an arm.
+ *
  * @see Mechanism2d
  */
 class MechanismLigament2d : public MechanismObject2d {

wpilibc/src/main/native/include/frc/smartdashboard/MechanismRoot2d.h

@@ -16,8 +16,12 @@ namespace frc {
 /**
  * Root Mechanism2d node.
  *
+ * A root is the anchor point of other nodes (such as ligaments).
+ *
  * Do not create objects of this class directly! Obtain pointers from the
  * Mechanism2d.GetRoot() factory method.
+ *
+ * <p>Append other nodes by using Append().
  */
 class MechanismRoot2d : private MechanismObject2d {
   friend class Mechanism2d;

wpilibj/src/main/java/edu/wpi/first/wpilibj/smartdashboard/Mechanism2d.java

@@ -13,10 +13,11 @@ import java.util.Map;
 import java.util.Map.Entry;
 
 /**
- * Visual 2D representation of arms, elevators, and general mechanisms; through a node-based API.
+ * Visual 2D representation of arms, elevators, and general mechanisms through a node-based API.
  *
- * <p>A Mechanism2d object is published and contains at least one root node. Other nodes (such as
- * ligaments) are recursively based on other nodes.
+ * <p>A Mechanism2d object is published and contains at least one root node. A root is the anchor
+ * point of other nodes (such as ligaments). Other nodes are recursively appended based on other
+ * nodes.
  *
  * @see MechanismObject2d
  * @see MechanismLigament2d
@@ -32,6 +33,8 @@ public final class Mechanism2d implements NTSendable {
   /**
    * Create a new Mechanism2d with the given dimensions and default color (dark blue).
    *
+   * <p>The dimensions represent the canvas that all the nodes are drawn on.
+   *
    * @param width the width
    * @param height the height
    */
@@ -42,6 +45,8 @@ public final class Mechanism2d implements NTSendable {
   /**
    * Create a new Mechanism2d with the given dimensions.
    *
+   * <p>The dimensions represent the canvas that all the nodes are drawn on.
+   *
    * @param width the width
    * @param height the height
    * @param backgroundColor the background color. Defaults to dark blue.

wpilibj/src/main/java/edu/wpi/first/wpilibj/smartdashboard/MechanismLigament2d.java

@@ -10,7 +10,8 @@ import edu.wpi.first.networktables.NetworkTableEntry;
 import edu.wpi.first.wpilibj.util.Color8Bit;
 
 /**
- * Ligament node on a Mechanism2d.
+ * Ligament node on a Mechanism2d. A ligament can have its length changed (like an elevator) or
+ * angle changed, like an arm.
  *
  * @see Mechanism2d
  */
@@ -43,7 +44,7 @@ public class MechanismLigament2d extends MechanismObject2d {
   }
 
   /**
-   * Create a new ligament with the default color (dark blue) and thickness (6).
+   * Create a new ligament with the default color (orange) and thickness (6).
    *
    * @param name The ligament's name.
    * @param length The ligament's length.

wpilibj/src/main/java/edu/wpi/first/wpilibj/smartdashboard/MechanismRoot2d.java

@@ -12,6 +12,8 @@ import java.util.Map;
 /**
  * Root Mechanism2d node.
  *
+ * <p>A root is the anchor point of other nodes (such as ligaments).
+ *
  * <p>Do not create objects of this class directly! Obtain instances from the {@link
  * Mechanism2d#getRoot(String, double, double)} factory method.
  *