From bc3d20bf2a7d5c36ec69806ce41f8b52fc7730b8 Mon Sep 17 00:00:00 2001
From: Maxime Coste <frrrwww@gmail.com>
Date: Mon, 27 Feb 2012 20:01:59 +0000
Subject: [PATCH] document Selection class

---
 src/selection.hh | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/selection.hh b/src/selection.hh
index d09a4785..dbc19fc0 100644
--- a/src/selection.hh
+++ b/src/selection.hh
@@ -6,6 +6,12 @@
 namespace Kakoune
 {
 
+// A Selection holds a buffer range
+//
+// The Selection class manage a (first, last) buffer iterators pair.
+// Selections are oriented, first may be > last, and inclusive.
+// Selection updates it's iterators according to modifications made
+// in the buffer.
 struct Selection : public ModificationListener
 {
     Selection(const BufferIterator& first, const BufferIterator& last);
@@ -14,7 +20,9 @@ struct Selection : public ModificationListener
 
     Selection& operator=(const Selection& other);
 
+    // returns min(first, last)
     BufferIterator begin() const;
+    // returns max(first, last) + 1
     BufferIterator end() const;
 
     const BufferIterator& first() const { return m_first; }
@@ -35,6 +43,9 @@ private:
 typedef std::vector<Selection> SelectionList;
 typedef std::vector<BufferString> CaptureList;
 
+// Selections are often associated with a capture list
+// like when they are created from a regex match with
+// capture groups.
 struct SelectionAndCaptures
 {
     Selection   selection;