From 50ce3d1549545336a54cac25654399af087ceab9 Mon Sep 17 00:00:00 2001
From: Maxime Coste <frrrwww@gmail.com>
Date: Wed, 11 Jan 2012 14:21:58 +0000
Subject: [PATCH] Document some Kakoune concepts, as Window, Buffer,
 DisplayAtom...

---
 src/buffer.hh         | 7 +++++++
 src/display_buffer.hh | 9 +++++++++
 src/filter.hh         | 4 ++++
 src/highlighter.hh    | 5 +++++
 src/window.hh         | 5 +++++
 5 files changed, 30 insertions(+)

diff --git a/src/buffer.hh b/src/buffer.hh
index dfa34c2d..3cedffd3 100644
--- a/src/buffer.hh
+++ b/src/buffer.hh
@@ -29,6 +29,7 @@ struct BufferCoord : LineAndColumn<BufferCoord>
         : LineAndColumn(other.line, other.column) {}
 };
 
+// A BufferIterator permits to iterate over the characters of a buffer
 class BufferIterator
 {
 public:
@@ -73,6 +74,7 @@ private:
     friend class Buffer;
 };
 
+// A Modification holds a single atomic modification to Buffer
 struct Modification
 {
     enum Type { Insert, Erase };
@@ -98,6 +100,11 @@ public:
     virtual void on_modification(const Modification& modification) = 0;
 };
 
+// A Buffer is a in-memory representation of a file
+//
+// The Buffer class permits to read and mutate this file
+// representation. It also manage modifications undo/redo and
+// provides tools to deal with the line/column nature of text.
 class Buffer
 {
 public:
diff --git a/src/display_buffer.hh b/src/display_buffer.hh
index b3cd8453..8ac5381e 100644
--- a/src/display_buffer.hh
+++ b/src/display_buffer.hh
@@ -45,6 +45,11 @@ enum class Color
     White
 };
 
+// A DisplayAtom is a string of text with it's display style.
+//
+// The DisplayAtom class references the buffer string it represents
+// with it's begin/end iterators and may replace it with another
+// text stored in the replacement_string field.
 struct DisplayAtom
 {
     DisplayAtom(const DisplayCoord& coord,
@@ -90,6 +95,10 @@ private:
     BufferString   m_replacement_text;
 };
 
+// A DisplayBuffer is the visual content of a Window as a DisplayAtom list
+//
+// The DisplayBuffer class provides means to mutate and iterator on it's
+// DisplayAtoms.
 class DisplayBuffer
 {
 public:
diff --git a/src/filter.hh b/src/filter.hh
index 4999b895..68930960 100644
--- a/src/filter.hh
+++ b/src/filter.hh
@@ -10,6 +10,10 @@ namespace Kakoune
 class Buffer;
 class Modification;
 
+// A Filter is a function which is applied to a Buffer and a pending
+// Modification in order to mutate the Buffer or the Modification
+// prior to it's application.
+
 typedef std::function<void (Buffer& buffer, Modification& modification)> FilterFunc;
 typedef std::pair<std::string, FilterFunc> FilterAndId;
 
diff --git a/src/highlighter.hh b/src/highlighter.hh
index 3000dd27..d2ff1dfb 100644
--- a/src/highlighter.hh
+++ b/src/highlighter.hh
@@ -8,6 +8,11 @@ namespace Kakoune
 
 class DisplayBuffer;
 
+// An Highlighter is a function which mutates a DisplayBuffer in order to
+// change the visual representation of a file. It could be changing text
+// color, adding information text (line numbering for example) or replacing
+// buffer content (folding for example)
+
 typedef std::function<void (DisplayBuffer& display_buffer)> HighlighterFunc;
 typedef std::pair<std::string, HighlighterFunc> HighlighterAndId;
 
diff --git a/src/window.hh b/src/window.hh
index e8fcc9e5..fa367c53 100644
--- a/src/window.hh
+++ b/src/window.hh
@@ -48,6 +48,11 @@ typedef std::vector<Selection> SelectionList;
 
 class IncrementalInserter;
 
+// A Window is an editing view onto a Buffer
+//
+// The Window class manage a set of selections and provides means to modify
+// both the selections and the buffer. It also handle the display of the
+// buffer with it's highlighters.
 class Window
 {
 public: