Document some Kakoune concepts, as Window, Buffer, DisplayAtom...

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:

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:

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;
 

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;
 

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: