Mercurial > hg > truffle
changeset 9989:b9b8af46c2b7
Upgrade the documentation for SourceSection, especially with respect to the specification of text locations.
author | Michael Van De Vanter <michael.van.de.vanter@oracle.com> |
---|---|
date | Mon, 10 Jun 2013 16:46:26 -0700 |
parents | b8b4d7f3e4aa |
children | fb2c8034e9b9 |
files | graal/com.oracle.truffle.api/src/com/oracle/truffle/api/SourceSection.java |
diffstat | 1 files changed, 35 insertions(+), 18 deletions(-) [+] |
line wrap: on
line diff
--- 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 */