From 9aaa640601b7e9431d792693b74e419934d2194d Mon Sep 17 00:00:00 2001
From: Richard Davey <rich@photonstorm.com>
Date: Sat, 15 Sep 2018 11:18:09 +0100
Subject: [PATCH] Finished Shape documentation

---
 src/gameobjects/shape/Shape.js                |  3 ++-
 src/gameobjects/shape/curve/Curve.js          | 14 ++++++++++++++
 src/gameobjects/shape/curve/CurveFactory.js   | 15 +++++++++++++++
 src/gameobjects/shape/grid/Grid.js            | 14 ++++++++++++++
 src/gameobjects/shape/grid/GridFactory.js     | 15 +++++++++++++++
 src/gameobjects/shape/isobox/IsoBox.js        | 13 +++++++++++++
 src/gameobjects/shape/isobox/IsoBoxFactory.js | 14 ++++++++++++++
 .../shape/isotriangle/IsoTriangle.js          | 14 ++++++++++++++
 .../shape/isotriangle/IsoTriangleFactory.js   | 15 +++++++++++++++
 src/gameobjects/shape/line/Line.js            | 12 ++++++++++++
 src/gameobjects/shape/line/LineFactory.js     | 13 +++++++++++++
 src/gameobjects/shape/polygon/Polygon.js      | 17 +++++++++++++++++
 .../shape/polygon/PolygonFactory.js           | 19 +++++++++++++++----
 src/gameobjects/shape/rectangle/Rectangle.js  |  8 ++++++++
 .../shape/rectangle/RectangleFactory.js       |  9 +++++++++
 src/gameobjects/shape/star/Star.js            | 14 ++++++++++++++
 src/gameobjects/shape/star/StarFactory.js     | 15 +++++++++++++++
 src/gameobjects/shape/triangle/Triangle.js    | 10 ++++++++++
 .../shape/triangle/TriangleFactory.js         | 11 +++++++++++
 19 files changed, 240 insertions(+), 5 deletions(-)

diff --git a/src/gameobjects/shape/Shape.js b/src/gameobjects/shape/Shape.js
index 30b69ad4e..30855730b 100644
--- a/src/gameobjects/shape/Shape.js
+++ b/src/gameobjects/shape/Shape.js
@@ -11,7 +11,8 @@ var Line = require('../../geom/line/Line');
 
 /**
  * @classdesc
- * A Shape Game Object.
+ * The Shape Game Object is a base class for the various different shapes, such as the Arc, Star or Polygon.
+ * You cannot add a Shape directly to your Scene, it is meant as a base for your own custom Shape classes.
  *
  * @class Shape
  * @extends Phaser.GameObjects.GameObject
diff --git a/src/gameobjects/shape/curve/Curve.js b/src/gameobjects/shape/curve/Curve.js
index e9ceb70ae..b8168012d 100644
--- a/src/gameobjects/shape/curve/Curve.js
+++ b/src/gameobjects/shape/curve/Curve.js
@@ -12,6 +12,20 @@ var Shape = require('../Shape');
 
 /**
  * @classdesc
+ * The Curve Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * To render a Curve Shape you must first create a `Phaser.Curves.Curve` object, then pass it to
+ * the Curve Shape in the constructor.
+ * 
+ * The Curve shape also has a `smoothness` property and corresponding `setSmoothness` method.
+ * This allows you to control how smooth the shape renders in WebGL, by controlling the number of iterations
+ * that take place during construction. Increase and decrease the default value for smoother, or more
+ * jagged, shapes.
  *
  * @class Curve
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/curve/CurveFactory.js b/src/gameobjects/shape/curve/CurveFactory.js
index 212af41f7..b39443974 100644
--- a/src/gameobjects/shape/curve/CurveFactory.js
+++ b/src/gameobjects/shape/curve/CurveFactory.js
@@ -11,6 +11,21 @@ var Curve = require('./Curve');
  * Creates a new Curve Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the Curve Game Object has been built into Phaser.
+ * 
+ * The Curve Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * To render a Curve Shape you must first create a `Phaser.Curves.Curve` object, then pass it to
+ * the Curve Shape in the constructor.
+ * 
+ * The Curve shape also has a `smoothness` property and corresponding `setSmoothness` method.
+ * This allows you to control how smooth the shape renders in WebGL, by controlling the number of iterations
+ * that take place during construction. Increase and decrease the default value for smoother, or more
+ * jagged, shapes.
  *
  * @method Phaser.GameObjects.GameObjectFactory#curve
  * @since 3.13.0
diff --git a/src/gameobjects/shape/grid/Grid.js b/src/gameobjects/shape/grid/Grid.js
index 542d3bd46..f8445356f 100644
--- a/src/gameobjects/shape/grid/Grid.js
+++ b/src/gameobjects/shape/grid/Grid.js
@@ -10,6 +10,20 @@ var GridRender = require('./GridRender');
 
 /**
  * @classdesc
+ * The Grid Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports only fill colors and cannot be stroked.
+ * 
+ * A Grid Shape allows you to display a grid in your game, where you can control the size of the
+ * grid as well as the width and height of the grid cells. You can set a fill color for each grid
+ * cell as well as an alternate fill color. When the alternate fill color is set then the grid
+ * cells will alternate the fill colors as they render, creating a chess-board effect. You can
+ * also optionally have an outline fill color. If set, this draws lines between the grid cells
+ * in the given color. If you specify an outline color with an alpha of zero, then it will draw
+ * the cells spaced out, but without the lines between them.
  *
  * @class Grid
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/grid/GridFactory.js b/src/gameobjects/shape/grid/GridFactory.js
index 755b059d3..1e1d63d67 100644
--- a/src/gameobjects/shape/grid/GridFactory.js
+++ b/src/gameobjects/shape/grid/GridFactory.js
@@ -11,6 +11,21 @@ var Grid = require('./Grid');
  * Creates a new Grid Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the Grid Game Object has been built into Phaser.
+ * 
+ * The Grid Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports only fill colors and cannot be stroked.
+ * 
+ * A Grid Shape allows you to display a grid in your game, where you can control the size of the
+ * grid as well as the width and height of the grid cells. You can set a fill color for each grid
+ * cell as well as an alternate fill color. When the alternate fill color is set then the grid
+ * cells will alternate the fill colors as they render, creating a chess-board effect. You can
+ * also optionally have an outline fill color. If set, this draws lines between the grid cells
+ * in the given color. If you specify an outline color with an alpha of zero, then it will draw
+ * the cells spaced out, but without the lines between them.
  *
  * @method Phaser.GameObjects.GameObjectFactory#grid
  * @since 3.13.0
diff --git a/src/gameobjects/shape/isobox/IsoBox.js b/src/gameobjects/shape/isobox/IsoBox.js
index 6505cc317..f3819132f 100644
--- a/src/gameobjects/shape/isobox/IsoBox.js
+++ b/src/gameobjects/shape/isobox/IsoBox.js
@@ -10,6 +10,19 @@ var Shape = require('../Shape');
 
 /**
  * @classdesc
+ * The IsoBox Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports only fill colors and cannot be stroked.
+ * 
+ * An IsoBox is an 'isometric' rectangle. Each face of it has a different fill color. You can set
+ * the color of the top, left and right faces of the rectangle respectively. You can also choose
+ * which of the faces are rendered via the `showTop`, `showLeft` and `showRight` properties.
+ * 
+ * You cannot view an IsoBox from under-neath, however you can change the 'angle' by setting
+ * the `projection` property.
  *
  * @class IsoBox
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/isobox/IsoBoxFactory.js b/src/gameobjects/shape/isobox/IsoBoxFactory.js
index 6f764ea6c..4a1ad7aa8 100644
--- a/src/gameobjects/shape/isobox/IsoBoxFactory.js
+++ b/src/gameobjects/shape/isobox/IsoBoxFactory.js
@@ -11,6 +11,20 @@ var IsoBox = require('./IsoBox');
  * Creates a new IsoBox Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the IsoBox Game Object has been built into Phaser.
+ * 
+ * The IsoBox Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports only fill colors and cannot be stroked.
+ * 
+ * An IsoBox is an 'isometric' rectangle. Each face of it has a different fill color. You can set
+ * the color of the top, left and right faces of the rectangle respectively. You can also choose
+ * which of the faces are rendered via the `showTop`, `showLeft` and `showRight` properties.
+ * 
+ * You cannot view an IsoBox from under-neath, however you can change the 'angle' by setting
+ * the `projection` property.
  *
  * @method Phaser.GameObjects.GameObjectFactory#isobox
  * @since 3.13.0
diff --git a/src/gameobjects/shape/isotriangle/IsoTriangle.js b/src/gameobjects/shape/isotriangle/IsoTriangle.js
index da8804cb1..ec4ccff6b 100644
--- a/src/gameobjects/shape/isotriangle/IsoTriangle.js
+++ b/src/gameobjects/shape/isotriangle/IsoTriangle.js
@@ -10,6 +10,20 @@ var Shape = require('../Shape');
 
 /**
  * @classdesc
+ * The IsoTriangle Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports only fill colors and cannot be stroked.
+ * 
+ * An IsoTriangle is an 'isometric' triangle. Think of it like a pyramid. Each face has a different
+ * fill color. You can set the color of the top, left and right faces of the triangle respectively
+ * You can also choose which of the faces are rendered via the `showTop`, `showLeft` and `showRight` properties.
+ * 
+ * You cannot view an IsoTriangle from under-neath, however you can change the 'angle' by setting
+ * the `projection` property. The `reversed` property controls if the IsoTriangle is rendered upside
+ * down or not.
  *
  * @class IsoTriangle
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/isotriangle/IsoTriangleFactory.js b/src/gameobjects/shape/isotriangle/IsoTriangleFactory.js
index 2984f843f..17b99dde7 100644
--- a/src/gameobjects/shape/isotriangle/IsoTriangleFactory.js
+++ b/src/gameobjects/shape/isotriangle/IsoTriangleFactory.js
@@ -11,6 +11,21 @@ var IsoTriangle = require('./IsoTriangle');
  * Creates a new IsoTriangle Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the IsoTriangle Game Object has been built into Phaser.
+ * 
+ * The IsoTriangle Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports only fill colors and cannot be stroked.
+ * 
+ * An IsoTriangle is an 'isometric' triangle. Think of it like a pyramid. Each face has a different
+ * fill color. You can set the color of the top, left and right faces of the triangle respectively
+ * You can also choose which of the faces are rendered via the `showTop`, `showLeft` and `showRight` properties.
+ * 
+ * You cannot view an IsoTriangle from under-neath, however you can change the 'angle' by setting
+ * the `projection` property. The `reversed` property controls if the IsoTriangle is rendered upside
+ * down or not.
  *
  * @method Phaser.GameObjects.GameObjectFactory#isotriangle
  * @since 3.13.0
diff --git a/src/gameobjects/shape/line/Line.js b/src/gameobjects/shape/line/Line.js
index 1618b9944..3b3b74c83 100644
--- a/src/gameobjects/shape/line/Line.js
+++ b/src/gameobjects/shape/line/Line.js
@@ -11,6 +11,18 @@ var LineRender = require('./LineRender');
 
 /**
  * @classdesc
+ * The Line Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports only stroke colors and cannot be filled.
+ * 
+ * A Line Shape allows you to draw a line between two points in your game. You can control the
+ * stroke color and thickness of the line. In WebGL only you can also specify a different
+ * thickness for the start and end of the line, allowing you to render lines that taper-off.
+ * 
+ * If you need to draw multiple lines in a sequence you may wish to use the Polygon Shape instead.
  *
  * @class Line
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/line/LineFactory.js b/src/gameobjects/shape/line/LineFactory.js
index dbbf77180..90c0e7d5c 100644
--- a/src/gameobjects/shape/line/LineFactory.js
+++ b/src/gameobjects/shape/line/LineFactory.js
@@ -11,6 +11,19 @@ var Line = require('./Line');
  * Creates a new Line Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the Line Game Object has been built into Phaser.
+ * 
+ * The Line Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports only stroke colors and cannot be filled.
+ * 
+ * A Line Shape allows you to draw a line between two points in your game. You can control the
+ * stroke color and thickness of the line. In WebGL only you can also specify a different
+ * thickness for the start and end of the line, allowing you to render lines that taper-off.
+ * 
+ * If you need to draw multiple lines in a sequence you may wish to use the Polygon Shape instead.
  *
  * @method Phaser.GameObjects.GameObjectFactory#line
  * @since 3.13.0
diff --git a/src/gameobjects/shape/polygon/Polygon.js b/src/gameobjects/shape/polygon/Polygon.js
index 03eee0ca3..4feb77454 100644
--- a/src/gameobjects/shape/polygon/Polygon.js
+++ b/src/gameobjects/shape/polygon/Polygon.js
@@ -14,6 +14,23 @@ var Smooth = require('../../../geom/polygon/Smooth');
 
 /**
  * @classdesc
+ * The Polygon Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * The Polygon Shape is created by providing a list of points, which are then used to create an
+ * internal Polygon geometry object. The points can be set from a variety of formats:
+ *
+ * - An array of Point or Vector2 objects: `[new Phaser.Math.Vec2(x1, y1), ...]`
+ * - An array of objects with public x/y properties: `[obj1, obj2, ...]`
+ * - An array of paired numbers that represent point coordinates: `[x1,y1, x2,y2, ...]`
+ * - An array of arrays with two elements representing x/y coordinates: `[[x1, y1], [x2, y2], ...]`
+ * 
+ * By default the `x` and `y` coordinates of this Shape refer to the center of it. However, depending
+ * on the coordinates of the points provided, the final shape may be rendered offset from its origin.
  *
  * @class Polygon
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/polygon/PolygonFactory.js b/src/gameobjects/shape/polygon/PolygonFactory.js
index 4c0b4bd24..bf886a8fb 100644
--- a/src/gameobjects/shape/polygon/PolygonFactory.js
+++ b/src/gameobjects/shape/polygon/PolygonFactory.js
@@ -10,14 +10,25 @@ var Polygon = require('./Polygon');
 /**
  * Creates a new Polygon Shape Game Object and adds it to the Scene.
  * 
- * The points can be set from a variety of formats:
+ * Note: This method will only be available if the Polygon Game Object has been built into Phaser.
+ * 
+ * The Polygon Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * The Polygon Shape is created by providing a list of points, which are then used to create an
+ * internal Polygon geometry object. The points can be set from a variety of formats:
  *
- * - An array of Point objects: `[new Phaser.Point(x1, y1), ...]`
+ * - An array of Point or Vector2 objects: `[new Phaser.Math.Vec2(x1, y1), ...]`
  * - An array of objects with public x/y properties: `[obj1, obj2, ...]`
  * - An array of paired numbers that represent point coordinates: `[x1,y1, x2,y2, ...]`
  * - An array of arrays with two elements representing x/y coordinates: `[[x1, y1], [x2, y2], ...]`
- *
- * Note: This method will only be available if the Polygon Game Object has been built into Phaser.
+ * 
+ * By default the `x` and `y` coordinates of this Shape refer to the center of it. However, depending
+ * on the coordinates of the points provided, the final shape may be rendered offset from its origin.
  *
  * @method Phaser.GameObjects.GameObjectFactory#polygon
  * @since 3.13.0
diff --git a/src/gameobjects/shape/rectangle/Rectangle.js b/src/gameobjects/shape/rectangle/Rectangle.js
index f6a886a5a..d05a6756b 100644
--- a/src/gameobjects/shape/rectangle/Rectangle.js
+++ b/src/gameobjects/shape/rectangle/Rectangle.js
@@ -11,6 +11,14 @@ var RectangleRender = require('./RectangleRender');
 
 /**
  * @classdesc
+ * The Rectangle Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * You can change the size of the rectangle by changing the `width` and `height` properties.
  *
  * @class Rectangle
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/rectangle/RectangleFactory.js b/src/gameobjects/shape/rectangle/RectangleFactory.js
index a0cb071a7..01960308b 100644
--- a/src/gameobjects/shape/rectangle/RectangleFactory.js
+++ b/src/gameobjects/shape/rectangle/RectangleFactory.js
@@ -11,6 +11,15 @@ var Rectangle = require('./Rectangle');
  * Creates a new Rectangle Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the Rectangle Game Object has been built into Phaser.
+ * 
+ * The Rectangle Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * You can change the size of the rectangle by changing the `width` and `height` properties.
  *
  * @method Phaser.GameObjects.GameObjectFactory#rectangle
  * @since 3.13.0
diff --git a/src/gameobjects/shape/star/Star.js b/src/gameobjects/shape/star/Star.js
index 6bfc1e615..0732ca56f 100644
--- a/src/gameobjects/shape/star/Star.js
+++ b/src/gameobjects/shape/star/Star.js
@@ -11,6 +11,20 @@ var Shape = require('../Shape');
 
 /**
  * @classdesc
+ * The Star Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * As the name implies, the Star shape will display a star in your game. You can control several
+ * aspects of it including the number of points that constitute the star. The default is 5. If
+ * you change it to 4 it will render as a diamond. If you increase them, you'll get a more spiky
+ * star shape.
+ * 
+ * You can also control the inner and outer radius, which is how 'long' each point of the star is.
+ * Modify these values to create more interesting shapes.
  *
  * @class Star
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/star/StarFactory.js b/src/gameobjects/shape/star/StarFactory.js
index 8932f99cc..9910605f2 100644
--- a/src/gameobjects/shape/star/StarFactory.js
+++ b/src/gameobjects/shape/star/StarFactory.js
@@ -11,6 +11,21 @@ var GameObjectFactory = require('../../GameObjectFactory');
  * Creates a new Star Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the Star Game Object has been built into Phaser.
+ * 
+ * The Star Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * As the name implies, the Star shape will display a star in your game. You can control several
+ * aspects of it including the number of points that constitute the star. The default is 5. If
+ * you change it to 4 it will render as a diamond. If you increase them, you'll get a more spiky
+ * star shape.
+ * 
+ * You can also control the inner and outer radius, which is how 'long' each point of the star is.
+ * Modify these values to create more interesting shapes.
  *
  * @method Phaser.GameObjects.GameObjectFactory#star
  * @since 3.13.0
diff --git a/src/gameobjects/shape/triangle/Triangle.js b/src/gameobjects/shape/triangle/Triangle.js
index 57ccfc701..255d01bcd 100644
--- a/src/gameobjects/shape/triangle/Triangle.js
+++ b/src/gameobjects/shape/triangle/Triangle.js
@@ -11,6 +11,16 @@ var TriangleRender = require('./TriangleRender');
 
 /**
  * @classdesc
+ * The Triangle Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * The Triangle consists of 3 lines, joining up to form a triangular shape. You can control the
+ * position of each point of these lines. The triangle is always closed and cannot have an open
+ * face. If you require that, consider using a Polygon instead.
  *
  * @class Triangle
  * @extends Phaser.GameObjects.Shape
diff --git a/src/gameobjects/shape/triangle/TriangleFactory.js b/src/gameobjects/shape/triangle/TriangleFactory.js
index 476f64781..0d92e65ec 100644
--- a/src/gameobjects/shape/triangle/TriangleFactory.js
+++ b/src/gameobjects/shape/triangle/TriangleFactory.js
@@ -11,6 +11,17 @@ var Triangle = require('./Triangle');
  * Creates a new Triangle Shape Game Object and adds it to the Scene.
  *
  * Note: This method will only be available if the Triangle Game Object has been built into Phaser.
+ * 
+ * The Triangle Shape is a Game Object that can be added to a Scene, Group or Container. You can
+ * treat it like any other Game Object in your game, such as tweening it, scaling it, or enabling
+ * it for input or physics. It provides a quick and easy way for you to render this shape in your
+ * game without using a texture, while still taking advantage of being fully batched in WebGL.
+ * 
+ * This shape supports both fill and stroke colors.
+ * 
+ * The Triangle consists of 3 lines, joining up to form a triangular shape. You can control the
+ * position of each point of these lines. The triangle is always closed and cannot have an open
+ * face. If you require that, consider using a Polygon instead.
  *
  * @method Phaser.GameObjects.GameObjectFactory#triangle
  * @since 3.13.0