 
   # 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

  #
  # The `Point.interpolate` method supports all the following forms:
  #
  #     Point.interpolate pt1, pt2, pos
  #     Point.interpolate x1, y1, pt2, pos
  #     Point.interpolate pt1, x2, y2, pos
  #     Point.interpolate x1, x2, x2, y2, pos
  @interpolate: (pt1, pt2, pos) ->
    args = []; args[i] = v for v,i in arguments


  # Returns a new point resulting of the addition of the
  # passed-in point to this point.
  #
  # ```coffeescript
  # point = new Point 4, 4
  # inc = point.add 1, 5
  # inc = point.add x: 0.2
  # inc = point.add new Point 1.8, 8
  # # inc = [Point(x=7,y=17)]
  # ```
  #
  # 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 new [Point]{agt.geom.Point}.
  add: (x, y) ->
    y = x.y or y if x?; y = 0 if isNaN y
    x = x.x or x if x?; x = 0 if isNaN x
    new Point @x + x, @y + y

  # Returns a new point that results of the subtraction of the
  # passed-in point to this point.
  #
  # ```coffeescript
  # point = new Point 4, 4
  # inc = point.subtract 1, 5
  # inc = point.subtract x: 0.2
  # inc = point.subtract new Point 1.8, 8
  # # inc = [Point(x=2,y=-9)]
  # ```
  #
  # 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 new [Point]{agt.geom.Point}.
  subtract: (x, y) ->
    y = x.y or y if x?; y = 0 if isNaN y
    x = x.x or x if x?; x = 0 if isNaN x
