--- a/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/SourceSection.java	Mon Jun 10 17:00:14 2013 +0200
+++ b/graal/com.oracle.truffle.api/src/com/oracle/truffle/api/SourceSection.java	Mon Jun 10 16:46:26 2013 -0700
@@ -23,7 +23,7 @@
 package com.oracle.truffle.api;
 
 /**
- * Represents a section in the source code of a guest language program.
+ * Represents a contiguous text section within the source code of a guest language program.
  */
 public class SourceSection {
 
@@ -35,13 +35,26 @@
     private final int charLength;
 
     /**
-     * Creates a new object representing a section in the source code of a guest language program.
+     * Creates a new object representing a contiguous text section within the source code of a guest
+     * language program.
+     * <p>
+     * The starting location of the section is specified using two different coordinate:
+     * <ul>
+     * <li><b>(row, column)</b>: rows and columns are 1-based, so the first character in a source
+     * file is at position {@code (1,1)}.</li>
+     * <li><b>character index</b>: 0-based offset of the character from the beginning of the source,
+     * so the first character in a file is at index {@code 0}.</li>
+     * </ul>
+     * The <b>newline</b> that terminates each line counts as a single character for the purpose of
+     * a character index. The (row,column) coordinates of a newline character should never appear in
+     * a text section.
+     * <p>
      * 
-     * @param source object representing the source program this is should be a section of
+     * @param source object representing the complete source program that contains this section
      * @param identifier an identifier used when printing the section
-     * @param startLine the index of the start line of the section
-     * @param startColumn the index of the start column of the section
-     * @param charIndex the index of the first character of the section
+     * @param startLine the 1-based number of the start line of the section
+     * @param startColumn the 1-based number of the start column of the section
+     * @param charIndex the 0-based index of the first character of the section
      * @param charLength the length of the section in number of characters
      */
     public SourceSection(Source source, String identifier, int startLine, int startColumn, int charIndex, int charLength) {
@@ -54,7 +67,7 @@
     }
 
     /**
-     * Returns the source object representing the source program this is a section of.
+     * Returns the object representing the source program that contains this section.
      * 
      * @return the source object
      */
@@ -63,38 +76,42 @@
     }
 
     /**
-     * Returns the index of the start line of this source section (inclusive).
+     * Returns 1-based line number of the first character in this source section (inclusive).
      * 
-     * @return the start line
+     * @return the starting line number
      */
     public final int getStartLine() {
         return startLine;
     }
 
     /**
-     * Returns the index of the start column of this source section (inclusive).
+     * Returns the 1-based column number of the first character in this source section (inclusive).
      * 
-     * @return the start column
+     * @return the starting column number
      */
     public final int getStartColumn() {
         return startColumn;
     }
 
     /**
-     * Returns the index of the first character of this section. All characters of the source can be
-     * retrieved via the {@link Source#getCode()} method.
+     * Returns the 0-based index of the first character in this source section.
+     * <p>
+     * The complete text of the source that contains this section can be retrieved via
+     * {@link Source#getCode()}.
      * 
-     * @return the character index
+     * @return the starting character index
      */
     public final int getCharIndex() {
         return charIndex;
     }
 
     /**
-     * Returns the length of this section in characters. All characters of the source can be
-     * retrieved via the {@link Source#getCode()} method.
+     * Returns the length of this source section in characters.
+     * <p>
+     * The complete text of the source that contains this section can be retrieved via
+     * {@link Source#getCode()}.
      * 
-     * @return the character length
+     * @return the number of characters in the section
      */
     public final int getCharLength() {
         return charLength;
@@ -110,7 +127,7 @@
     }
 
     /**
-     * Returns the code represented by this code section.
+     * Returns text of the code represented by this source section.
      * 
      * @return the code as a String object
      */