Better docs for positions

1 files changed, 45 insertions, 1 deletions

diff --git a/src/compiler/scala/tools/nsc/util/Position.scala b/src/compiler/scala/tools/nsc/util/Position.scala
index a63454fd44..ff2be66702 100644
--- a/src/compiler/scala/tools/nsc/util/Position.scala
+++ b/src/compiler/scala/tools/nsc/util/Position.scala
@@ -1,6 +1,7 @@
 /* NSC -- new Scala compiler
  * Copyright 2005-2009 LAMP/EPFL
  * @author  Martin Odersky
+ *
  */
 // $Id$
 
@@ -10,7 +11,50 @@ package util
 object Position {
   val tabInc = 8
 }
-
+/** The class and its subclasses represent positions of ASTs and symbols.
+ *  Except for NoPosition and FakePos, every position refers to a SourceFile
+ *  and to an offset in the sourcefile (its `point'). For batch compilation,
+ *  that's all. For interactive IDE's there are also RangePositions
+ *  and TransparentPositions. A RangePosition indicates a start and an end
+ *  in addition to its point. TransparentPositions are a subclass of RangePositions.
+ *  Range positions that are not transparent are called opaque.
+ *  Trees with RangePositions need to satisfy the following invariants.
+ *
+ *  INV1: A tree with an offset position never contains a child
+ *        with a range position
+ *  INV2: If the child of a tree with a range position also has a range position,
+ *        then the child's range is contained in the parent's range.
+ *  INV3: Opaque range positions of children of the same node are non-overlapping
+ *        (this means their overlap is at most a single point).
+ *
+ *  The following tests are useful on positions:
+ *
+ *  pos.isDefined     true if position is not a NoPosition nor a FakePosition
+ *  pos.isRange       true if position is a range
+ *  pos.isOpaqueRange true if position is an opaque range
+ *
+ *  The following accessor methods are provided:
+ *
+ *  pos.source        The source file of the position, which must be defined
+ *  pos.point         The offset of the position's point, which must be defined
+ *  pos.start         The start of the position, which must be a range
+ *  pos.end           The end of the position, which must be a range
+ *
+ *  There are also convenience methods, such as
+ *
+ *  pos.startOrPoint
+ *  pos.endOrPoint
+ *  pos.pointOrElse(default)
+ *
+ *  Theseare less strict about the kind of position on which they can be applied.
+ *
+ *  The following conversion methods are often used:
+ *
+ *  pos.focus           converts a range position to an offset position, keeping its point;
+ *                      returns all other positions unchanged.
+ *  pos.makeTransparent converts an opaque range position into a transparent one.
+ *                      returns all other positions unchanged.
+ */
 trait Position {
 
   /** An optional value containing the source file referred to by this position, or