+# Public: Represents a point in a buffer in row/column coordinates. Every public
+# method that takes a point also accepts a *point-compatible* {Array}. This means
+# a 2-element array containing {Number}s representing the row and column. So the
+# following are equivalent:
+#
+# new Point(1, 2)
+# [1, 2]
 module.exports =
 class Point
+  # Public: Convert any point-compatible object to a {Point}.
+  #
+  # * object:
+  #     This can be an object that's already a {Point}, in which case it's
+  #     simply returned, or an array containing two {Numbers} representing the
+  #     row and column.
+  #
+  # * copy:
+  #     An optional boolean indicating whether to force the copying of objects
+  #     that are already points.
+  #
+  # Returns: A {Point} based on the given object.
   @fromObject: (object, copy) ->
     if object instanceof Point
       if copy then object.copy() else object


      new Point(row, column)

  @min: (point1, point2) ->
    point1 = @fromObject(point1)
    point2 = @fromObject(point2)


  constructor: (@row=0, @column=0) ->

  # Public: Returns a new {Point} with the same row and column.
  copy: ->
    new Point(@row, @column)

  # Public: Makes this point immutable and returns itself.
  freeze: ->
    Object.freeze(this)

  # Public: Return a new {Point} based on shifting this point by the given delta,
  # which is represented by another {Point}.
  translate: (delta) ->
    {row, column} = Point.fromObject(delta)
    new Point(@row + row, @column + column)

  # Public:
  #
  # * other: A {Point} or point-compatible {Array}.
  #
  # Returns:
  #  * -1 if this point precedes the argument.
  #  * 0 if this point is equivalent to the argument.
  #  * 1 if this point follows the argument.
  compare: (other) ->
    if @row > other.row
      1
