 
   # Returns the dot product of this point and the passed-in point.
   #
-  #     dot = new Point(5,6).dot(7,8)
-  #     # dot = 83
+  # ```coffeescript
+  # dot = new Point(5,6).dot(7,8)
+  # # dot = 83
+  # ```
+  #
+  # x - A {Number} for the x coordinate or a point-like {Object}
+  #     to initialize the point.
+  # y - A {Number} for the y coordinate if the first argument
+  #     was also a number.
+  #
+  # Returns a {Number}.
   dot: (x, y) ->
     @noPoint 'dot' if not x? and not y?
     isPoint = @isPoint x


  # Returns the length of the current vector represented by this point.
  #
  #     length = point.length()
  length: -> Math.sqrt (@x * @x) + (@y * @y)

  # Returns the angle in degrees formed by the vector.
  #
  #     angle = point.angle()
  angle: -> Math.atan2 @y, @x

  # Given a triangle formed by this point, the passed-in point


  # Converts polar coordinates in cartesian coordinates.
  #
  # ```coffeescript
  # Point.polar 90, 10 # [Point(x=0,y=10)]
  # ```
  #
  # angle - A {Number} of the angle in radians.
  # length - A {Number} of the vector length in pixels.
  #
  # Returns a [Point]{agt.geom.Point} instance.
  @polar: (angle, length=1) -> new Point Math.sin(angle) * length,
                                         Math.cos(angle) * length

