docs: elevate the Entity class reference to peak quality

src/framework/entity.js

@@ -67,16 +67,40 @@ const releaseTempArray = (a) => {
 };
 
 /**
- * The Entity is a core primitive of a PlayCanvas application. Generally speaking, any object in
- * your application will be represented by an Entity, along with a set of {@link Component}s. Each
- * component enables a particular capability. For example, the {@link RenderComponent} enables an
- * entity to render a 3D model, and the {@link ScriptComponent} enables an entity to run code that
- * implements custom behavior.
+ * An Entity is the core primitive of a PlayCanvas application. Every object in a scene (a camera, a
+ * light, a 3D model, a sound source, a piece of UI, or your own gameplay object) is represented by
+ * an Entity. On its own, an Entity is simply a named node in the scene graph; it gains behavior
+ * from the {@link Component}s attached to it.
  *
- * Entity is a subclass of {@link GraphNode} which allows entities to form a tree-like hierarchy
- * (based on parent/child relationships). The root of the entity hierarchy can be queried with
- * {@link AppBase#root}. Entities inherit a 3D transform from {@link GraphNode} which allows them
- * to be positioned, rotated and scaled.
+ * An Entity therefore brings together two things:
+ *
+ * - A transform: Entity extends {@link GraphNode}, so it has a position, rotation and scale, and
+ * can be parented to other entities to form a hierarchy. The root of that hierarchy is
+ * {@link AppBase#root}, and child entities inherit the transforms of their ancestors.
+ * - A set of components: each {@link Component} adds a single capability. For example, a
+ * {@link CameraComponent} renders the scene, a {@link LightComponent} lights it, a
+ * {@link RenderComponent} draws a 3D mesh, and a {@link ScriptComponent} runs your own code.
+ *
+ * Add a capability with {@link Entity#addComponent}, access it later through the matching property
+ * (such as {@link Entity#camera} or {@link Entity#render}), and remove it with
+ * {@link Entity#removeComponent}. An entity, together with all of its descendants and their
+ * components, can be enabled or disabled as a group via {@link GraphNode#enabled}, and removed from
+ * the scene with {@link Entity#destroy}.
+ *
+ * @example
+ * // Create an entity, give it a camera component, position it, and add it to the scene
+ * const camera = new pc.Entity('camera');
+ * camera.addComponent('camera', {
+ *     clearColor: new pc.Color(0.1, 0.1, 0.1)
+ * });
+ * camera.setPosition(0, 0, 10);
+ * app.root.addChild(camera);
+ * @example
+ * // Entities form a hierarchy: a child inherits its parent's transform
+ * const parent = new pc.Entity('parent');
+ * const child = new pc.Entity('child');
+ * parent.addChild(child);
+ * parent.setLocalPosition(5, 0, 0); // moves both parent and child
  */
 class Entity extends GraphNode {
     /**
@@ -417,8 +441,8 @@ class Entity extends GraphNode {
      * Search the entity and all of its descendants for the first component of specified type.
      *
      * @param {string} type - The name of the component type to retrieve.
-     * @returns {Component} A component of specified type, if the entity or any of its descendants
-     * has one. Returns undefined otherwise.
+     * @returns {Component|null} A component of specified type, if the entity or any of its
+     * descendants has one. Returns null otherwise.
      * @example
      * // Get the first found light component in the hierarchy tree that starts with this entity
      * const light = entity.findComponent("light");