--- a/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/source/SourceSectionTest.java	Mon Nov 16 18:00:16 2015 +0100
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/source/SourceSectionTest.java	Thu Nov 19 15:58:26 2015 +0100
@@ -38,7 +38,7 @@
 
     private final Source shortSource = Source.fromText("01", null);
 
-    private final Source longSource = Source.fromText("01234\n67\n9\n", null);
+    private final Source longSource = Source.fromText("01234\n67\n9\n", "long");
 
     public void emptySourceTest0() {
         SourceSection section = emptySource.createSection("test", 0, 0);
@@ -84,4 +84,17 @@
         assertEquals(section.getCode(), "");
     }
 
+    @Test
+    public void testGetCode() {
+        assertEquals("01234", longSource.createSection("test", 0, 5).getCode());
+        assertEquals("67", longSource.createSection("test", 6, 2).getCode());
+        assertEquals("9", longSource.createSection("test", 9, 1).getCode());
+    }
+
+    @Test
+    public void testGetShortDescription() {
+        assertEquals("long:1", longSource.createSection("test", 0, 5).getShortDescription());
+        assertEquals("long:2", longSource.createSection("test", 6, 2).getShortDescription());
+        assertEquals("long:3", longSource.createSection("test", 9, 1).getShortDescription());
+    }
 }

--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/source/SourceSection.java	Mon Nov 16 18:00:16 2015 +0100
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/source/SourceSection.java	Thu Nov 19 15:58:26 2015 +0100
@@ -170,9 +170,10 @@
     }
 
     /**
-     * Returns text described by this section.
+     * Returns the source code fragment described by this section.
      *
-     * @return the code as a String object
+     * @return the code as a string, or {@code "<unavailable>"} if the SourceSection was created
+     *         using {@link #createUnavailable}.
      */
     public String getCode() {
         return source == null ? "<unavailable>" : source.getCode(charIndex, charLength);
@@ -182,7 +183,7 @@
      * Returns a short description of the source section, using just the file name, rather than its
      * full path.
      *
-     * @return a short description of the source section
+     * @return a short description of the source section formatted as {@code <filename>:<line>}.
      */
     public String getShortDescription() {
         if (source == null) {
@@ -191,6 +192,13 @@
         return String.format("%s:%d", source.getShortName(), startLine);
     }
 
+    /**
+     * Returns an implementation-defined string representation of this source section to be used for
+     * debugging purposes only.
+     *
+     * @see #getCode()
+     * @see #getShortDescription()
+     */
     @Override
     public String toString() {
         return getShortDescription();