Bug 461262 - ISourceElement: remove hard dependency on ISourceFile

Change-Id: Ib8d162f991f55e0d1c4db1a6f1b9d75f112a8c54

18 files changed, 255 insertions, 284 deletions

diff --git a/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/SourceElementUtil.java b/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/SourceElementUtil.java
index 488241e4..2a3ae6b9 100644
--- a/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/SourceElementUtil.java
+++ b/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/SourceElementUtil.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -20,51 +20,60 @@ import org.eclipse.ui.texteditor.ITextEditor;
 /**
  * Utilities for <code>ISourceElement</code>s.
  * <p>
- * Note how this code is free from specifics of the Foo Model, 
+ * Note how this code is free from specifics of the Foo Model,
  * thanks to the uniform API provided by Handly.
  * </p>
  */
 public class SourceElementUtil
 {
     /**
-     * Returns the smallest element within the given source file 
-     * that includes the given source position, or <code>null</code> 
-     * if the given position is not within the text range of this source file, 
-     * or if the source file does not exist or an exception occurs while 
-     * accessing its corresponding resource. If no finer grained element 
-     * is found at the position, the source file itself is returned.
+     * Returns the smallest element within the given element that includes
+     * the given source position, or <code>null</code> if the given position
+     * is not within the source range of the given element, or if the
+     * given element does not exist or an exception occurs while accessing
+     * its corresponding resource. If no finer grained element is found
+     * at the position, the given element is returned.
      * <p>
-     * As a side effect, reconciles the given source file.
+     * As a side effect, if the given element is contained in a source file,
+     * the source file will be reconciled.
      * </p>
      *
-     * @param sourceFile the source file (not <code>null</code>)
-     * @param position a source position inside the source file (0-based)
-     * @return the innermost element enclosing the given source position, 
-     *  or <code>null</code> if none (including the source file itself)
+     * @param element a source element (not <code>null</code>)
+     * @param position a source position (0-based)
+     * @return the innermost element enclosing the given source position,
+     *  or <code>null</code> if none (including the given element)
      */
-    public static ISourceElement getSourceElement(ISourceFile sourceFile,
+    public static ISourceElement getElementAt(ISourceElement element,
         int position)
     {
-        try
+        ISourceFile sourceFile;
+        if (element instanceof ISourceFile)
+            sourceFile = (ISourceFile)element;
+        else
+            sourceFile = element.getAncestor(ISourceFile.class);
+        if (sourceFile != null)
         {
-            sourceFile.reconcile(false, null);
-        }
-        catch (CoreException e)
-        {
-            Activator.log(e.getStatus());
-            return null;
+            try
+            {
+                sourceFile.reconcile(false, null);
+            }
+            catch (CoreException e)
+            {
+                Activator.log(e.getStatus());
+                return null;
+            }
         }
-        return sourceFile.getElementAt(position, null);
+        return element.getElementAt(position, null);
     }
 
     /**
-     * Selects and reveals the identifying range of the given source element 
-     * in the given text editor. Returns <code>false</code> if the identifying 
+     * Selects and reveals the identifying range of the given source element
+     * in the given text editor. Returns <code>false</code> if the identifying
      * range is not set or cannot be obtained (e.g., the element does not exist). 
      *
      * @param textEditor not <code>null</code>
      * @param element not <code>null</code>
-     * @return <code>true</code> if the element was successfully revealed 
+     * @return <code>true</code> if the element was successfully revealed
      *  in the editor; <code>false</code> otherwise
      */
     public static boolean revealInTextEditor(ITextEditor textEditor,
@@ -84,7 +93,7 @@ public class SourceElementUtil
             return false;
         }
         TextRange identifyingRange = info.getIdentifyingRange();
-        if (identifyingRange.isNull())
+        if (identifyingRange == null)
             return false;
         textEditor.selectAndReveal(identifyingRange.getOffset(),
             identifyingRange.getLength());
diff --git a/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/model/FooFileStructureBuilder.java b/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/model/FooFileStructureBuilder.java
index a1440296..34fcdbfc 100644
--- a/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/model/FooFileStructureBuilder.java
+++ b/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/model/FooFileStructureBuilder.java
@@ -110,7 +110,7 @@ class FooFileStructureBuilder
     private static TextRange toTextRange(ITextRegion region)
     {
         if (region == null || region.equals(ITextRegion.EMPTY_REGION))
-            return TextRange.NULL_RANGE;
+            return null;
         else
             return new TextRange(region.getOffset(), region.getLength());
     }
diff --git a/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/outline/FooOutlinePage.java b/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/outline/FooOutlinePage.java
index 6172e68c..a3e390ce 100644
--- a/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/outline/FooOutlinePage.java
+++ b/org.eclipse.handly.examples.basic.ui/src/org/eclipse/handly/internal/examples/basic/ui/outline/FooOutlinePage.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -24,7 +24,6 @@ import org.eclipse.handly.model.IElementChangeListener;
 import org.eclipse.handly.model.IHandle;
 import org.eclipse.handly.model.IHandleDelta;
 import org.eclipse.handly.model.ISourceElement;
-import org.eclipse.handly.model.ISourceFile;
 import org.eclipse.jface.text.ITextSelection;
 import org.eclipse.jface.viewers.IPostSelectionProvider;
 import org.eclipse.jface.viewers.ISelection;
@@ -294,10 +293,8 @@ public final class FooOutlinePage
                 Object input = treeViewer.getInput();
                 if (!(input instanceof ISourceElement))
                     return Status.OK_STATUS;
-                ISourceFile sourceFile =
-                    ((ISourceElement)input).getSourceFile();
                 final ISourceElement element =
-                    SourceElementUtil.getSourceElement(sourceFile,
+                    SourceElementUtil.getElementAt((ISourceElement)input,
                         baseSelection.getOffset()); // reconciles the source file as a side effect
                 if (element == null)
                     return Status.OK_STATUS;
@@ -309,12 +306,8 @@ public final class FooOutlinePage
                     public void run()
                     {
                         Control control = treeViewer.getControl();
-                        Object input = treeViewer.getInput();
                         if (control == null
                             || control.isDisposed()
-                            || !(input instanceof ISourceElement)
-                            || !element.getSourceFile().equals(
-                                ((ISourceElement)input).getSourceFile())
                             || !baseSelection.equals(selection)
                             || !baseSelection.equals(editor.getSelectionProvider().getSelection()))
                             return; // the world has changed -> no work needs to be done
diff --git a/org.eclipse.handly.ui/src/org/eclipse/handly/internal/ui/SourceElementUtil.java b/org.eclipse.handly.ui/src/org/eclipse/handly/internal/ui/SourceElementUtil.java
index 1d54e032..1ca54042 100644
--- a/org.eclipse.handly.ui/src/org/eclipse/handly/internal/ui/SourceElementUtil.java
+++ b/org.eclipse.handly.ui/src/org/eclipse/handly/internal/ui/SourceElementUtil.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -22,40 +22,49 @@ import org.eclipse.handly.util.TextRange;
 public class SourceElementUtil
 {
     /**
-     * Returns the smallest element within the given source file 
-     * that includes the given source position, or <code>null</code> 
-     * if the given position is not within the text range of this source file, 
-     * or if the source file does not exist or an exception occurs while 
-     * accessing its corresponding resource. If no finer grained element 
-     * is found at the position, the source file itself is returned.
+     * Returns the smallest element within the given element that includes
+     * the given source position, or <code>null</code> if the given position
+     * is not within the source range of the given element, or if the
+     * given element does not exist or an exception occurs while accessing
+     * its corresponding resource. If no finer grained element is found
+     * at the position, the given element is returned.
      * <p>
-     * As a side effect, reconciles the given source file.
+     * As a side effect, if the given element is contained in a source file,
+     * the source file will be reconciled.
      * </p>
      *
-     * @param sourceFile the source file (not <code>null</code>)
-     * @param position a source position inside the source file (0-based)
-     * @return the innermost element enclosing the given source position, 
-     *  or <code>null</code> if none (including the source file itself)
+     * @param element a source element (not <code>null</code>)
+     * @param position a source position (0-based)
+     * @return the innermost element enclosing the given source position,
+     *  or <code>null</code> if none (including the given element)
      */
-    public static ISourceElement getSourceElement(ISourceFile sourceFile,
+    public static ISourceElement getElementAt(ISourceElement element,
         int position)
     {
-        try
-        {
-            sourceFile.reconcile(false, null);
-        }
-        catch (CoreException e)
+        ISourceFile sourceFile;
+        if (element instanceof ISourceFile)
+            sourceFile = (ISourceFile)element;
+        else
+            sourceFile = element.getAncestor(ISourceFile.class);
+        if (sourceFile != null)
         {
-            Activator.log(e.getStatus());
-            return null;
+            try
+            {
+                sourceFile.reconcile(false, null);
+            }
+            catch (CoreException e)
+            {
+                Activator.log(e.getStatus());
+                return null;
+            }
         }
-        return sourceFile.getElementAt(position, null);
+        return element.getElementAt(position, null);
     }
 
     /**
-     * Returns the identifying range of the given source element, 
-     * or <code>null</code> if the identifying range is not set 
-     * or cannot be obtained (e.g., the element does not exist). 
+     * Returns the identifying range of the given source element,
+     * or <code>null</code> if the identifying range is not set
+     * or cannot be obtained (e.g., the element does not exist).
      *
      * @param element not <code>null</code>
      * @return the identifying range of the element or <code>null</code>
diff --git a/org.eclipse.handly.ui/src/org/eclipse/handly/ui/outline/SourceElementLinkingHelper.java b/org.eclipse.handly.ui/src/org/eclipse/handly/ui/outline/SourceElementLinkingHelper.java
index c40efe47..6dde98fa 100644
--- a/org.eclipse.handly.ui/src/org/eclipse/handly/ui/outline/SourceElementLinkingHelper.java
+++ b/org.eclipse.handly.ui/src/org/eclipse/handly/ui/outline/SourceElementLinkingHelper.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -16,7 +16,6 @@ import org.eclipse.core.runtime.Status;
 import org.eclipse.core.runtime.jobs.Job;
 import org.eclipse.handly.internal.ui.SourceElementUtil;
 import org.eclipse.handly.model.ISourceElement;
-import org.eclipse.handly.model.ISourceFile;
 import org.eclipse.handly.util.TextRange;
 import org.eclipse.jface.dialogs.IPageChangeProvider;
 import org.eclipse.jface.text.ITextSelection;
@@ -96,7 +95,7 @@ public class SourceElementLinkingHelper
             return;
         TextRange identifyingRange =
             SourceElementUtil.getIdentifyingRange((ISourceElement)element);
-        if (identifyingRange == null || identifyingRange.isNull())
+        if (identifyingRange == null)
             return;
         editor.selectAndReveal(identifyingRange.getOffset(),
             identifyingRange.getLength());
@@ -139,9 +138,8 @@ public class SourceElementLinkingHelper
         Object input = getOutlinePage().getTreeViewer().getInput();
         if (!(input instanceof ISourceElement))
             return null;
-        ISourceFile sourceFile = ((ISourceElement)input).getSourceFile();
         ISourceElement element =
-            SourceElementUtil.getSourceElement(sourceFile,
+            SourceElementUtil.getElementAt((ISourceElement)input,
                 selection.getOffset());
         if (element == null)
             return null;
@@ -226,12 +224,8 @@ public class SourceElementLinkingHelper
                     Control control = getOutlinePage().getControl();
                     TreeViewer treeViewer = getOutlinePage().getTreeViewer();
                     IEditorPart editor = getOutlinePage().getEditor();
-                    Object input = treeViewer.getInput();
                     if (control == null
                         || control.isDisposed()
-                        || !(input instanceof ISourceElement)
-                        || !((ISourceFile)baseInput).getSourceFile().equals(
-                            ((ISourceFile)input).getSourceFile())
                         || !baseSelection.equals(selection)
                         || !baseSelection.equals(editor.getSite().getSelectionProvider().getSelection()))
                         return; // the world has changed -> no work needs to be done
diff --git a/org.eclipse.handly.ui/src/org/eclipse/handly/ui/quickoutline/SourceElementOutlinePopup.java b/org.eclipse.handly.ui/src/org/eclipse/handly/ui/quickoutline/SourceElementOutlinePopup.java
index ec8b212c..d5627148 100644
--- a/org.eclipse.handly.ui/src/org/eclipse/handly/ui/quickoutline/SourceElementOutlinePopup.java
+++ b/org.eclipse.handly.ui/src/org/eclipse/handly/ui/quickoutline/SourceElementOutlinePopup.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -12,7 +12,6 @@ package org.eclipse.handly.ui.quickoutline;
 
 import org.eclipse.handly.internal.ui.SourceElementUtil;
 import org.eclipse.handly.model.ISourceElement;
-import org.eclipse.handly.model.ISourceFile;
 import org.eclipse.handly.util.TextRange;
 import org.eclipse.jface.text.ITextSelection;
 import org.eclipse.jface.text.TextSelection;
@@ -33,8 +32,7 @@ public abstract class SourceElementOutlinePopup
         Object input = getTreeViewer().getInput();
         if (!(input instanceof ISourceElement))
             return null;
-        ISourceFile sourceFile = ((ISourceElement)input).getSourceFile();
-        return SourceElementUtil.getSourceElement(sourceFile,
+        return SourceElementUtil.getElementAt((ISourceElement)input,
             ((ITextSelection)hostSelection).getOffset());
     }
 
@@ -45,7 +43,7 @@ public abstract class SourceElementOutlinePopup
             return false;
         TextRange identifyingRange =
             SourceElementUtil.getIdentifyingRange((ISourceElement)outlineElement);
-        if (identifyingRange == null || identifyingRange.isNull())
+        if (identifyingRange == null)
             return false;
         TextSelection textSelection =
             new TextSelection(identifyingRange.getOffset(),
diff --git a/org.eclipse.handly.ui/src/org/eclipse/handly/ui/viewer/ProblemMarkerLabelDecorator.java b/org.eclipse.handly.ui/src/org/eclipse/handly/ui/viewer/ProblemMarkerLabelDecorator.java
index cb8561a8..98c24071 100644
--- a/org.eclipse.handly.ui/src/org/eclipse/handly/ui/viewer/ProblemMarkerLabelDecorator.java
+++ b/org.eclipse.handly.ui/src/org/eclipse/handly/ui/viewer/ProblemMarkerLabelDecorator.java
@@ -81,7 +81,7 @@ public class ProblemMarkerLabelDecorator
             if (!sourceConstruct.exists())
                 return null;
             textRange = sourceConstruct.getSourceElementInfo().getFullRange();
-            if (textRange.isNull())
+            if (textRange == null)
                 return null;
         }
         return findMaxProblemSeverity(resource, IResource.DEPTH_INFINITE,
diff --git a/org.eclipse.handly.xtext.ui/src/org/eclipse/handly/xtext/ui/editor/HandlyXtextEditorCallback.java b/org.eclipse.handly.xtext.ui/src/org/eclipse/handly/xtext/ui/editor/HandlyXtextEditorCallback.java
index ab976d25..9093167a 100644
--- a/org.eclipse.handly.xtext.ui/src/org/eclipse/handly/xtext/ui/editor/HandlyXtextEditorCallback.java
+++ b/org.eclipse.handly.xtext.ui/src/org/eclipse/handly/xtext/ui/editor/HandlyXtextEditorCallback.java
@@ -115,7 +115,7 @@ public class HandlyXtextEditorCallback
             return null;
         return (SourceFile)getSourceFileFactory().getSourceFile(file);
     }
-    
+
     protected ISourceFileFactory getSourceFileFactory()
     {
         return sourceFileFactory;
@@ -287,7 +287,8 @@ public class HandlyXtextEditorCallback
                     resetEditorHighlightRange(args);
                     return e.getStatus();
                 }
-                setEditorHighlightRange(args, r.getOffset(), r.getLength());
+                if (r != null)
+                    setEditorHighlightRange(args, r.getOffset(), r.getLength());
             }
             return Status.OK_STATUS;
         }
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceConstruct.java b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceConstruct.java
index 6f888b53..1cbc5438 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceConstruct.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceConstruct.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -11,7 +11,7 @@
 package org.eclipse.handly.model;
 
 /**
- * Represents a construct inside a source file.
+ * Represents a programming language's structural construct.
  * 
  * @noimplement This interface is not intended to be implemented by clients.
  */
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceElement.java b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceElement.java
index 466fa4a5..d22dc546 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceElement.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceElement.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -11,26 +11,33 @@
 package org.eclipse.handly.model;
 
 import org.eclipse.core.runtime.CoreException;
+import org.eclipse.handly.snapshot.ISnapshot;
 
 /**
- * Represents a source file or a construct inside a source file. 
- * The children are source constructs and appear in the order 
- * in which they are declared in the source.
+ * Common protocol for elements that may have associated source code.
+ * The children are of type {@link ISourceConstruct} and appear
+ * in declaration order.
  * 
  * @noimplement This interface is not intended to be implemented by clients.
- * @noextend This interface is not intended to be extended by clients.
  */
 public interface ISourceElement
     extends IHandle
 {
     /**
-     * Returns the source file containing this element. 
-     * Returns this element if it is a source file. 
-     * This is a handle-only method.
-     * 
-     * @return the source file (never <code>null</code>)
+     * Returns the smallest element within this element that includes
+     * the given source position, or <code>null</code> if the given position
+     * is not within the source range of this element, or if this element does not
+     * exist or an exception occurs while accessing its corresponding resource,
+     * or if snapshot inconsistency is detected. If no finer grained element
+     * is found at the position, this element itself is returned.
+     *
+     * @param position a source position (0-based)
+     * @param base a snapshot on which the given position is based,
+     *  or <code>null</code> if the snapshot is unknown or doesn't matter
+     * @return the innermost element enclosing the given source position,
+     *  or <code>null</code> if none (including this element itself)
      */
-    ISourceFile getSourceFile();
+    ISourceElement getElementAt(int position, ISnapshot base);
 
     /**
      * Returns an object holding cached structure and properties for this element.
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceElementInfo.java b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceElementInfo.java
index 0c405e51..18915551 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceElementInfo.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceElementInfo.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -14,8 +14,9 @@ import org.eclipse.handly.snapshot.ISnapshot;
 import org.eclipse.handly.util.TextRange;
 
 /**
- * Holds cached structure and properties for a source element. Those 
- * structure and properties correlate to a known snapshot of the source file.
+ * Holds cached structure and properties for a source element. If the element
+ * has associated source code, those structure and properties correlate to
+ * a specific snapshot of the source.
  * 
  * @see ISourceElement
  * @noimplement This interface is not intended to be implemented by clients.
@@ -23,66 +24,70 @@ import org.eclipse.handly.util.TextRange;
 public interface ISourceElementInfo
 {
     /**
-     * Returns the source file's snapshot on which this object is based.
+     * Returns the source snapshot on which this object is based,
+     * or <code>null</code> if the element has no associated source code.
      *
-     * @return the source file's snapshot on which this object is based 
-     *  (never <code>null</code>)
+     * @return the source snapshot on which this object is based,
+     *  or <code>null</code> if the element has no associated source code
      */
     ISnapshot getSnapshot();
 
     /**
-     * Returns the cached value of the given property, or <code>null</code> 
+     * Returns the cached value of the given property, or <code>null</code>
      * if the property is not set.
      * <p>
-     * Note that the result correlates to a source file's {@link #getSnapshot() 
-     * snapshot} and may be inconsistent with the current contents 
-     * of the source file.
-     * </p> 
+     * Note that the result correlates to a source {@link #getSnapshot()
+     * snapshot} (if there is one) and may be inconsistent with the current
+     * source contents.
+     * </p>
      *
      * @param property a source element's property (not <code>null</code>)
-     * @return the cached value of the given property, or <code>null</code> 
+     * @return the cached value of the given property, or <code>null</code>
      *  if the property is not set
      */
     <T> T get(ISourceElement.Property<T> property);
 
     /**
-     * Returns the cached children of the source element. The children are 
-     * in the order in which they appear in the source file.
+     * Returns the cached children of the source element. The children appear
+     * in declaration order.
      * <p>
-     * Note that the result correlates to a source file's {@link #getSnapshot() 
-     * snapshot} and may be inconsistent with the current contents 
-     * of the source file.
-     * </p> 
+     * Note that the result correlates to a source {@link #getSnapshot()
+     * snapshot} (if there is one) and may be inconsistent with the current
+     * source contents.
+     * </p>
      *
-     * @return the cached children of the source element 
+     * @return the cached children of the source element
      *  (never <code>null</code>)
      */
     ISourceConstruct[] getChildren();
 
     /**
-     * Returns the cached text range of the source element.
+     * Returns the cached text range of the source element. If the element
+     * has no associated source code, <code>null</code> is returned.
      * <p>
-     * Note that the result correlates to a source file's {@link #getSnapshot() 
-     * snapshot} and may be inconsistent with the current contents 
-     * of the source file.
+     * Note that the result correlates to a source {@link #getSnapshot()
+     * snapshot} (if there is one) and may be inconsistent with the current
+     * source contents.
      * </p>
      *
-     * @return the cached text range of the source element 
-     *  (never <code>null</code>)
+     * @return the cached text range of the source element,
+     *  or <code>null</code> if the element has no associated source code
      */
     TextRange getFullRange();
 
     /**
-     * Returns the cached text range of the source element's identifier. 
+     * Returns the cached text range of the source element's identifier.
      * Can be used for highlighting the element in a text editor, etc.
+     * If the element does not have a name or has no associated source code,
+     * <code>null</code> is returned.
      * <p>
-     * Note that the result correlates to a source file's {@link #getSnapshot() 
-     * snapshot} and may be inconsistent with the current contents 
-     * of the source file.
+     * Note that the result correlates to a source {@link #getSnapshot()
+     * snapshot} (if there is one) and may be inconsistent with the current
+     * source contents.
      * </p>
      *
-     * @return the cached text range of the source element's identifier 
-     *  (never <code>null</code>)
+     * @return the cached text range of the source element's identifier,
+     *  or <code>null</code> if not available
      */
     TextRange getIdentifyingRange();
 }
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceFile.java b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceFile.java
index da902911..50e549a3 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceFile.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceFile.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -14,7 +14,6 @@ import org.eclipse.core.resources.IFile;
 import org.eclipse.core.runtime.CoreException;
 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.handly.buffer.IBuffer;
-import org.eclipse.handly.snapshot.ISnapshot;
 
 /**
  * Represents a source file.
@@ -25,8 +24,7 @@ public interface ISourceFile
     extends ISourceElement
 {
     /**
-     * Convenience method. Same as <code>getResource()</code>, 
-     * but saves a downcast. This is a handle-only method.
+     * Returns the underlying workspace file. This is a handle-only method.
      *
      * @return the underlying {@link IFile} (never <code>null</code>)
      * @see #getResource()
@@ -34,49 +32,33 @@ public interface ISourceFile
     IFile getFile();
 
     /**
-     * Returns the smallest element within this source file that includes 
-     * the given source position, or <code>null</code> if the given position 
-     * is not within the text range of this source file, or if the source file 
-     * does not exist or an exception occurs while accessing its corresponding 
-     * resource, or if snapshot inconcistency is detected. If no finer grained 
-     * element is found at the position, the source file itself is returned.
-     *
-     * @param position a source position inside the source file (0-based)
-     * @param base a snapshot on which the given position is based, 
-     *  or <code>null</code> if the snapshot is unknown or doesn't matter
-     * @return the innermost element enclosing the given source position, 
-     *  or <code>null</code> if none (including the source file itself).
-     */
-    ISourceElement getElementAt(int position, ISnapshot base);
-
-    /**
      * Returns whether this source file is a working copy.
      *
-     * @return <code>true</code> if this source file is a working copy, 
+     * @return <code>true</code> if this source file is a working copy,
      *  <code>false</code> otherwise
      */
     boolean isWorkingCopy();
 
     /**
-     * Returns whether this source file needs reconciling. 
-     * The source file needs reconciling if it is a working copy and 
+     * Returns whether this source file needs reconciling.
+     * The source file needs reconciling if it is a working copy and
      * its buffer has been modified since the last time it was reconciled.
      *
-     * @return <code>true</code> if this source file needs reconciling, 
+     * @return <code>true</code> if this source file needs reconciling,
      *  <code>false</code> otherwise
      */
     boolean needsReconciling();
 
     /**
-     * Makes this working copy consistent with its buffer by updating 
-     * the element's structure and properties as necessary. Does nothing 
-     * if the source file is not in working copy mode. The boolean argument 
-     * allows to force problem detection even if the working copy is already 
+     * Makes this working copy consistent with its buffer by updating
+     * the element's structure and properties as necessary. Does nothing
+     * if the source file is not in working copy mode. The boolean argument
+     * allows to force problem detection even if the working copy is already
      * consistent with its buffer.
      *
-     * @param forceProblemDetection indicates whether problems should be 
+     * @param forceProblemDetection indicates whether problems should be
      *  recomputed even if the source hasn't changed
-     * @param monitor a progress monitor, or <code>null</code> 
+     * @param monitor a progress monitor, or <code>null</code>
      *  if progress reporting is not desired
      * @throws CoreException if this working copy cannot be reconciled
      */
@@ -84,30 +66,30 @@ public interface ISourceFile
         throws CoreException;
 
     /**
-     * Returns the buffer opened for this source file. There may be at most one 
-     * (in terms of <code>equals</code>) buffer opened for a given source file 
-     * at a time. Thus, buffers may be shared by multiple clients. Note that 
-     * the returned buffer may have unsaved changes if it has been modified 
+     * Returns the buffer opened for this source file. There may be at most one
+     * (in terms of <code>equals</code>) buffer opened for a given source file
+     * at a time. Thus, buffers may be shared by multiple clients. Note that
+     * the returned buffer may have unsaved changes if it has been modified
      * by another client.
      * <p>
-     * The client takes (potentially shared) ownership of the returned buffer 
-     * and is responsible for disposing it when finished. The buffer will be 
-     * closed only after it is disposed by every owner. The buffer must not 
+     * The client takes (potentially shared) ownership of the returned buffer
+     * and is responsible for disposing it when finished. The buffer will be
+     * closed only after it is disposed by every owner. The buffer must not
      * be accessed by clients which don't own it.
      * </p>
      * <p>
-     * If <code>create == false</code> and there is no buffer currently 
+     * If <code>create == false</code> and there is no buffer currently
      * opened for this source file, <code>null</code> is returned.
      * </p>
      *
-     * @param create indicates whether a new buffer should be created 
+     * @param create indicates whether a new buffer should be created
      *  if none already exists for this source file
-     * @param monitor a progress monitor, or <code>null</code> 
+     * @param monitor a progress monitor, or <code>null</code>
      *  if progress reporting is not desired
-     * @return the buffer opened for this source file, or <code>null</code> 
-     *  if <code>create == false</code> and there is no buffer currently opened 
+     * @return the buffer opened for this source file, or <code>null</code>
+     *  if <code>create == false</code> and there is no buffer currently opened
      *  for this source file
-     * @throws CoreException if this source file does not exist 
+     * @throws CoreException if this source file does not exist
      *  or if its contents cannot be accessed
      * @see IBuffer
      */
@@ -117,10 +99,10 @@ public interface ISourceFile
     /**
      * Convenience method. Same as <code>openBuffer(true, monitor)</code>.
      *
-     * @param monitor a progress monitor, or <code>null</code> 
+     * @param monitor a progress monitor, or <code>null</code>
      *  if progress reporting is not desired
      * @return the buffer opened for this source file (never <code>null</code>)
-     * @throws CoreException if this source file does not exist 
+     * @throws CoreException if this source file does not exist
      *  or if its contents cannot be accessed
      * @see #openBuffer(boolean, IProgressMonitor)
      */
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceConstruct.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceConstruct.java
index 05790209..6a748fa0 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceConstruct.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceConstruct.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -18,7 +18,7 @@ import org.eclipse.handly.model.IHandle;
 import org.eclipse.handly.model.ISourceConstruct;
 
 /**
- * Represents a construct inside a source file. 
+ * Common superclass of {@link ISourceConstruct} implementations.
  */
 public abstract class SourceConstruct
     extends SourceElement
@@ -69,13 +69,7 @@ public abstract class SourceConstruct
     @Override
     public final IResource getResource()
     {
-        return getSourceFile().getResource();
-    }
-
-    @Override
-    public SourceFile getSourceFile()
-    {
-        return ((SourceElement)parent).getSourceFile();
+        return parent.getResource();
     }
 
     @Override
@@ -104,39 +98,50 @@ public abstract class SourceConstruct
     @Override
     public final boolean close()
     {
-        // SourceFile builds the whole structure
-        // and controls child lifecycle
+        // The openable parent builds the whole structure and controls child life-cycle
         throw new AssertionError("This method should not be called"); //$NON-NLS-1$
     }
 
     @Override
     protected final void validateExistence() throws CoreException
     {
-        // SourceFile builds the whole structure
-        // and determines child existence
+        // The openable parent builds the whole structure and determines child existence
         throw new AssertionError("This method should not be called"); //$NON-NLS-1$
     }
 
     @Override
     protected final Body newBody()
     {
-        // must return <code>null</code>.
-        // SourceFile builds the whole structure 
-        // and knows how to create child bodies
+        // The openable parent builds the whole structure and knows how to create child bodies
         return null;
     }
 
     @Override
     protected final Handle getOpenableParent()
     {
-        return getSourceFile();
+        Handle result = parent;
+        // Source constructs are never openable
+        while (result instanceof SourceConstruct)
+            result = result.parent;
+        return result;
     }
 
     @Override
     protected final void buildStructure(Body body,
         Map<IHandle, Body> newElements) throws CoreException
     {
-        // SourceFile builds the whole structure 
+        // The openable parent builds the whole structure
         throw new AssertionError("This method should not be called"); //$NON-NLS-1$
     }
+
+    @Override
+    protected void toStringName(StringBuilder builder)
+    {
+        super.toStringName(builder);
+        if (occurrenceCount > 1)
+        {
+            builder.append('#');
+            builder.append(occurrenceCount);
+        }
+    }
 }
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceElement.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceElement.java
index b7983214..6e8342d5 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceElement.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceElement.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -15,19 +15,20 @@ import org.eclipse.handly.model.ISourceElement;
 import org.eclipse.handly.model.ISourceElementInfo;
 import org.eclipse.handly.snapshot.ISnapshot;
 import org.eclipse.handly.snapshot.StaleSnapshotException;
+import org.eclipse.handly.util.TextRange;
 
 /**
  * Common superclass of {@link ISourceElement} implementations.
  * 
- * @noextend This class is not intended to be extended by clients. Clients 
- *  should extend either {@link SourceFile} or {@link SourceConstruct} instead.
+ * @see SourceFile
+ * @see SourceConstruct
  */
 public abstract class SourceElement
     extends Handle
     implements ISourceElement
 {
     /**
-     * Constructs a handle for a source element with the given parent element 
+     * Constructs a handle for a source element with the given parent element
      * and the given name.
      * 
      * @param parent the parent of the element (not <code>null</code>)
@@ -42,41 +43,58 @@ public abstract class SourceElement
     }
 
     @Override
+    public final ISourceElement getElementAt(int position, ISnapshot base)
+    {
+        try
+        {
+            return getElementAt(this, position, base);
+        }
+        catch (CoreException e)
+        {
+            // ignore
+        }
+        catch (StaleSnapshotException e)
+        {
+            // ignore
+        }
+        return null;
+    }
+
+    @Override
     public ISourceElementInfo getSourceElementInfo() throws CoreException
     {
         return (ISourceElementInfo)getBody();
     }
 
-    public abstract SourceFile getSourceFile();
-
-    /**
-     * Returns the smallest element within the given element that includes 
-     * the given source position, or <code>null</code> if the given position 
-     * is not within the source range of the given element. If no finer grained 
+    /*
+     * Returns the smallest element within the given element that includes
+     * the given source position, or <code>null</code> if the given position
+     * is not within the source range of the given element. If no finer grained
      * element is found at the position, the given element is returned.
      *
      * @param element a source element (not <code>null</code>)
      * @param position a source position (0-based)
-     * @param base a snapshot on which the given position is based, 
+     * @param base a snapshot on which the given position is based,
      *  or <code>null</code> if the snapshot is unknown or doesn't matter
-     * @return the innermost element within the given element enclosing 
-     *  the given source position, or <code>null</code> if none (including 
+     * @return the innermost element within the given element enclosing
+     *  the given source position, or <code>null</code> if none (including
      *  the given element)
-     * @throws CoreException if the given element does not exist or if an 
+     * @throws CoreException if the given element does not exist or if an
      *  exception occurs while accessing its corresponding resource
-     * @throws StaleSnapshotException if snapshot inconsistency is detected, 
-     *  i.e. the given element's current structure and properties are based on 
+     * @throws StaleSnapshotException if snapshot inconsistency is detected,
+     *  i.e. the given element's current structure and properties are based on
      *  a different snapshot
      */
-    static ISourceElement getElementAt(ISourceElement element, int position,
-        ISnapshot base) throws CoreException
+    private static ISourceElement getElementAt(ISourceElement element,
+        int position, ISnapshot base) throws CoreException
     {
         ISourceElementInfo info = element.getSourceElementInfo();
         if (base != null && !base.isEqualTo(info.getSnapshot()))
         {
             throw new StaleSnapshotException();
         }
-        if (!info.getFullRange().covers(position))
+        TextRange textRange = info.getFullRange();
+        if (textRange == null || !textRange.covers(position))
             return null; // not found
         ISourceElement[] children = info.getChildren();
         for (int i = children.length - 1; i >= 0; i--)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceElementBody.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceElementBody.java
index 51b7bce1..5f3d47d2 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceElementBody.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceElementBody.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -22,7 +22,7 @@ import org.eclipse.handly.snapshot.ISnapshot;
 import org.eclipse.handly.util.TextRange;
 
 /**
- * Holds cached structure and properties for a source element. 
+ * Holds cached structure and properties for a source element.
  * Can be subclassed for specific kinds of elements.
  * 
  * @see ISourceElementInfo
@@ -35,8 +35,8 @@ public class SourceElementBody
 
     private ISnapshot snapshot;
     private Property[] properties = NO_PROPERTIES;
-    private TextRange fullRange = TextRange.NULL_RANGE;
-    private TextRange identifyingRange = TextRange.NULL_RANGE;
+    private TextRange fullRange;
+    private TextRange identifyingRange;
 
     @Override
     public ISourceConstruct[] getChildren()
@@ -80,8 +80,7 @@ public class SourceElementBody
     }
 
     /**
-     * Sets the value of the given property according to the {@link 
-     * #getSnapshot() snapshot}.
+     * Sets the value of the given property.
      *
      * @param p a source element's property (not <code>null</code>)
      * @param value the value of the given property (may be <code>null</code>)
@@ -110,40 +109,32 @@ public class SourceElementBody
     }
 
     /**
-     * Sets the source file's snapshot on which this object is based. 
+     * Sets the source snapshot on which this object is based.
      *
-     * @param snapshot not <code>null</code>
+     * @param snapshot
      */
     public void setSnapshot(ISnapshot snapshot)
     {
-        if (snapshot == null)
-            throw new IllegalArgumentException();
         this.snapshot = snapshot;
     }
 
     /**
-     * Sets the text range of the source element in the {@link #getSnapshot() 
-     * snapshot}.
+     * Sets the text range of the source element.
      *
-     * @param fullRange not <code>null</code>
+     * @param fullRange
      */
     public void setFullRange(TextRange fullRange)
     {
-        if (fullRange == null)
-            throw new IllegalArgumentException();
         this.fullRange = fullRange;
     }
 
     /**
-     * Sets the text range of the source element's identifier in the {@link 
-     * #getSnapshot() snapshot}. 
+     * Sets the text range of the source element's identifier.
      *
-     * @param identifyingRange not <code>null</code>
+     * @param identifyingRange
      */
     public void setIdentifyingRange(TextRange identifyingRange)
     {
-        if (identifyingRange == null)
-            throw new IllegalArgumentException();
         this.identifyingRange = identifyingRange;
     }
 
@@ -175,14 +166,14 @@ public class SourceElementBody
     /**
      * Returns whether the given property has changed value.
      * <p>
-     * Default implementation compares the new value and the old value 
+     * Default implementation compares the new value and the old value
      * for equality (arrays are compared with <code>Arrays.equals</code>).
      * </p>
      *
      * @param propertyName the name of the property (never <code>null</code>)
      * @param newValue the new value of the property (may be <code>null</code>)
      * @param oldValue the old value of the property (may be <code>null</code>)
-     * @return <code>true</code> if the property has changed value, and 
+     * @return <code>true</code> if the property has changed value, and
      *  <code>false</code> otherwise
      */
     protected boolean isPropertyChanged(String propertyName, Object newValue,
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceFile.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceFile.java
index 91c58494..2ea1b003 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceFile.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/SourceFile.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -24,17 +24,15 @@ import org.eclipse.handly.buffer.IBuffer;
 import org.eclipse.handly.buffer.TextFileBuffer;
 import org.eclipse.handly.internal.Activator;
 import org.eclipse.handly.model.IHandle;
-import org.eclipse.handly.model.ISourceElement;
 import org.eclipse.handly.model.ISourceFile;
 import org.eclipse.handly.snapshot.ISnapshot;
 import org.eclipse.handly.snapshot.ISnapshotProvider;
 import org.eclipse.handly.snapshot.NonExpiringSnapshot;
-import org.eclipse.handly.snapshot.StaleSnapshotException;
 import org.eclipse.handly.snapshot.TextFileSnapshot;
 import org.eclipse.handly.util.TextRange;
 
 /**
- * Represents a source file.
+ * Common superclass of {@link ISourceFile} implementations.
  */
 public abstract class SourceFile
     extends SourceElement
@@ -76,30 +74,6 @@ public abstract class SourceFile
     }
 
     @Override
-    public final SourceFile getSourceFile()
-    {
-        return this;
-    }
-
-    @Override
-    public final ISourceElement getElementAt(int position, ISnapshot base)
-    {
-        try
-        {
-            return getElementAt(this, position, base);
-        }
-        catch (CoreException e)
-        {
-            // ignore
-        }
-        catch (StaleSnapshotException e)
-        {
-            // ignore
-        }
-        return null;
-    }
-
-    @Override
     public final IBuffer openBuffer(boolean create, IProgressMonitor monitor)
         throws CoreException
     {
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/StructureHelper.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/StructureHelper.java
index 1324c394..870eeb5e 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/StructureHelper.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/StructureHelper.java
@@ -18,7 +18,8 @@ import java.util.Map;
 import org.eclipse.handly.model.IHandle;
 
 /**
- * A useful superclass for structure builders.
+ * A useful superclass for structure builders of "terminal openables"
+ * such as source files.
  * <p>
  * Subclasses provide a client API of the structure builder. 
  * Subclasses call {@link #addChild(Body, IHandle, Body)} and 
diff --git a/org.eclipse.handly/src/org/eclipse/handly/util/TextRange.java b/org.eclipse.handly/src/org/eclipse/handly/util/TextRange.java
index 0b860352..84ef5604 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/util/TextRange.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/util/TextRange.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2014 1C LLC.
+ * Copyright (c) 2014, 2015 1C-Soft LLC and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -11,8 +11,8 @@
 package org.eclipse.handly.util;
 
 /**
- * Describes a certain range in an indexed text store. Text stores are 
- * for example documents or strings. A text range is defined by its offset 
+ * Describes a certain range in an indexed text store. Text stores are
+ * for example documents or strings. A text range is defined by its offset
  * into the text store and its length.
  * <p>
  * A text range is a value object. Its offset and length do not change over time.
@@ -20,11 +20,6 @@ package org.eclipse.handly.util;
  */
 public final class TextRange
 {
-    /**
-     * Represents {@link #isNull() null} range.
-     */
-    public static final TextRange NULL_RANGE = new TextRange(-1, 0);
-
     private final int offset;
     private final int length;
 
@@ -36,7 +31,7 @@ public final class TextRange
      */
     public TextRange(int offset, int length)
     {
-        if (offset < -1) // -1 -> 'null' range
+        if (offset < 0)
             throw new IllegalArgumentException();
         if (length < 0)
             throw new IllegalArgumentException();
@@ -47,8 +42,7 @@ public final class TextRange
     }
 
     /**
-     * @return the 0-based index of the first character of this text range. 
-     *  Returns -1 for a {@link #isNull() null} range
+     * @return the 0-based index of the first character of this text range
      */
     public int getOffset()
     {
@@ -56,7 +50,7 @@ public final class TextRange
     }
 
     /**
-     * @return the number of characters in this text range. Returns 0 for 
+     * @return the number of characters in this text range. Returns 0 for
      *  an {@link #isEmpty() empty} range
      */
     public int getLength()
@@ -65,8 +59,8 @@ public final class TextRange
     }
 
     /**
-     * @return the 0-based index of the next character of this text range. 
-     *  The returned value is the result of the following calculation: 
+     * @return the 0-based index of the next character of this text range.
+     *  The returned value is the result of the following calculation:
      *  <code>getOffset() + getLength()</code>
      */
     public int getEndOffset()
@@ -75,7 +69,7 @@ public final class TextRange
     }
 
     /**
-     * @return <code>true</code> if this text range is empty 
+     * @return <code>true</code> if this text range is empty
      *  (i.e. its length is 0), and <code>false</code> otherwise
      */
     public boolean isEmpty()
@@ -84,21 +78,11 @@ public final class TextRange
     }
 
     /**
-     * @return <code>true</code> if this text range does not describe a range 
-     *  with a non-negative offset (i.e. a 'real' range) in a text store, 
-     *  and <code>false</code> otherwise.
-     */
-    public boolean isNull()
-    {
-        return NULL_RANGE.equals(this);
-    }
-
-    /**
-     * Returns whether this text range covers the given position, 
+     * Returns whether this text range covers the given position,
      * excluding the {@link #getEndOffset() end offset} of the range.
      *
      * @param position a text position (0-based)
-     * @return <code>true</code> if this text range strictly covers the given 
+     * @return <code>true</code> if this text range strictly covers the given
      *  position, and <code>false</code> otherwise
      * @see #covers(int)
      */
@@ -108,11 +92,11 @@ public final class TextRange
     }
 
     /**
-     * Returns whether this text range covers the given position, 
+     * Returns whether this text range covers the given position,
      * including the {@link #getEndOffset() end offset} of the range.
      *
      * @param position a text position (0-based)
-     * @return <code>true</code> if this text range covers the given position, 
+     * @return <code>true</code> if this text range covers the given position,
      *  and <code>false</code> otherwise
      * @see #strictlyCovers(int)
      */
@@ -151,6 +135,6 @@ public final class TextRange
     @Override
     public String toString()
     {
-        return "offset=" + offset + ", length=" + length; //$NON-NLS-1$ //$NON-NLS-2$
+        return "[offset=" + offset + ", length=" + length + ']'; //$NON-NLS-1$ //$NON-NLS-2$
     }
 }