From 29ee461d293f93b52f3a5be1a033e4bc1b04e626 Mon Sep 17 00:00:00 2001
From: Garen Torikian <gjtorikian@gmail.com>
Date: Wed, 26 Dec 2012 23:15:52 -0800
Subject: [PATCH] Add documentation

---
 lib/ace/document.js | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/lib/ace/document.js b/lib/ace/document.js
index 9dd18674..28ff3537 100644
--- a/lib/ace/document.js
+++ b/lib/ace/document.js
@@ -592,6 +592,22 @@ var Document = function(text) {
         }
     };
 
+    /**
+     * Converts an index position in a document to a `{row, column}` object.
+     *
+     * Index refers to the "absolute position" of a character in the document. For example:
+     *
+     * ```javascript
+     * var x = 0; // 10 characters, plus one for newline
+     * var y = -1;
+     * ```
+     * 
+     * Here, `y` is an index 15: 11 characters for the first row, and 5 characters until `y` in the second.
+     *
+     * @param {Number} index An index to convert
+     * @param {Number} startRow=0 The row from which to start the conversion
+     * @returns {Object} A `{row, column}` object of the `index` position
+     */
     this.indexToPosition = function(index, startRow) {
         var lines = this.$lines || this.getAllLines();
         var newlineLength = this.getNewLineCharacter().length;
@@ -603,6 +619,22 @@ var Document = function(text) {
         return {row: l-1, column: lines[l-1].length};
     };
 
+    /**
+     * Converts the `{row, column}` position in a document to the character's index.
+     *
+     * Index refers to the "absolute position" of a character in the document. For example:
+     *
+     * ```javascript
+     * var x = 0; // 10 characters, plus one for newline
+     * var y = -1;
+     * ```
+     * 
+     * Here, `y` is an index 15: 11 characters for the first row, and 5 characters until `y` in the second.
+     *
+     * @param {Object} pos The `{row, column}` to convert
+     * @param {Number} startRow=0 The row from which to start the conversion
+     * @returns {Number} The index position in the document
+     */
     this.positionToIndex = function(pos, startRow) {
         var lines = this.$lines || this.getAllLines();
         var newlineLength = this.getNewLineCharacter().length;