Merge remote branch 'origin/sentence-cleanup'

libwccl/sentencecontext.h

@@ -21,10 +21,12 @@ public:
 	/// Constructor, wraps the Sentence and sets position to 0
 	explicit SentenceContext(const boost::shared_ptr<Corpus2::Sentence>& s);
 
-	/// Returns a copy of this with a cloned underlyiong sentence
+	/// Returns a copy of this with a cloned underlying sentence.
 	SentenceContext duplicate() const;
 
 	/// Cloning -- clones the underlying sentence as well
+    /// Note: slower than duplicate() and less useful since you should
+    /// prefer to keep SentenceContexts as values, not pointers
 	SentenceContext* clone() const;
 
 	/// Underlying sentence accessor
@@ -107,7 +109,7 @@ public:
 		++position_;
 	}
 
-	/// Reste position to point to the first token
+	/// Reset position to point to the first token
 	void goto_start() {
 		position_ = 0;
 	}
@@ -152,10 +154,21 @@ public:
 		return at(position_);
 	}
 
+    /// Translate a Position into an absolute index into
+    /// the Sentence wrapped by this SentenceContext.
+    /// This takes proper care of the special `begin', 
+    /// `end' and `nowhere' Positions.
 	int get_abs_position(const Position& position) const;
 
+    /// Translate a Position into an relative index into
+    /// the Sentence wrapped by this SentenceContext.
+    /// (Relative to the current position).
+    /// This takes proper care of the special `begin', 
+    /// `end' and `nowhere' Positions.
 	int get_rel_position(const Position& position) const;
 
+    /// Helper function for translatin special Positions
+    /// (`begin', `end' and `nowhere')
 	int translate_special_position(int pos) const {
 		switch (pos) {
 		case Position::Begin:
@@ -168,8 +181,8 @@ public:
 			return position_ + pos;
 		}
 	}
-private:
 
+private:
 	/// The wrapped sentence
 	boost::shared_ptr<Corpus2::Sentence> sentence_;