From 5e48fdff28c4fe9f3f966639537ea92ec4be1eab Mon Sep 17 00:00:00 2001
From: veillettem <martin.veillette@gmail.com>
Date: Tue, 28 Jun 2016 09:02:54 -0400
Subject: [PATCH] add JSDOC to Plane3  (see #49)

---
 js/Plane3.js | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/js/Plane3.js b/js/Plane3.js
index e5996a3..9fd0fc9 100644
--- a/js/Plane3.js
+++ b/js/Plane3.js
@@ -13,17 +13,18 @@ define( function( require ) {
   var dot = require( 'DOT/dot' );
   var Vector3 = require( 'DOT/Vector3' );
 
-  /*
-   * @constructor
+  /**
+   *
    * @param {Vector3} normal - A normal vector (perpendicular) to the plane
    * @param {number} distance - The signed distance to the plane from the origin, so that normal.times( distance )
    *                            will be a point on the plane.
+   * @constructor
    */
   function Plane3( normal, distance ) {
-    this.normal = normal;
-    this.distance = distance;
+    this.normal = normal; // @public (read-only)
+    this.distance = distance; // @public (read-only)
 
-    assert && assert( Math.abs( normal.magnitude() - 1 ) < 0.01 );
+    assert && assert( Math.abs( normal.magnitude() - 1 ) < 0.01, 'the normal vector must be a unit vector' );
 
     phetAllocation && phetAllocation( 'Plane3' );
   }
@@ -33,9 +34,11 @@ define( function( require ) {
   Plane3.prototype = {
     constructor: Plane3,
 
-    /*
+    /**
+     * Returns the intersection point of a ray with this plane.
+     * @public
      * @param {Ray3} ray
-     * @returns The intersection {Vector3} of the ray with the plane
+     * @returns {Vector3}
      */
     intersectWithRay: function( ray ) {
       return ray.pointAtDistance( ray.distanceToPlane( this ) );
@@ -46,10 +49,15 @@ define( function( require ) {
   Plane3.XZ = new Plane3( new Vector3( 0, 1, 0 ), 0 );
   Plane3.YZ = new Plane3( new Vector3( 1, 0, 0 ), 0 );
 
-  /*
+  /**
+   * Returns a new plane that passes through three points $(\vec{a},\vec{b},\vec{c})$
+   * The normal of the plane points along $\vec{c-a} \times \vec{b-a}$
+   * Passing three collinear points will return null
+   * @public
    * @param {Vector3} a - first point
    * @param {Vector3} b - second point
    * @param {Vector3} c - third point
+   * @returns {Plane3|null}
    */
   Plane3.fromTriangle = function( a, b, c ) {
     var normal = ( c.minus( a ) ).cross( b.minus( a ) );