diff --git a/src/actions.h b/src/actions.h
index e37007b..6cb021f 100644
--- a/src/actions.h
+++ b/src/actions.h
@@ -23,8 +23,8 @@ namespace opustags {
         void list(int streamno, const Tags&) {}
 
         // Transform the tags at will.
-        // Returns true if the tags were indeed modified, false to cancel any
-        // kind of modification.
+        // Returns true if the tags were indeed modified, false if they weren't.
+        // The latter case may be used for optimization.
         bool edit(int streamno, Tags&) { return false; }
 
         // The work is done.
@@ -37,10 +37,23 @@ namespace opustags {
 
     // Decode a file and call the handler's list method every time a tags
     // header is read.
+    //
+    // Use:
+    //   ogg::Decoder dec(std::ifstream("in.ogg"));
+    //   TagsLister lister(options);
+    //   list_tags(dec, lister);
+    //
     void list_tags(ogg::Decoder&, TagsHandler&);
 
     // Forward the input data to the output stream, transforming tags on-the-go
     // with the handler's edit method.
+    //
+    // Use:
+    //   ogg::Decoder dec(std::ifstream("in.ogg"));
+    //   ogg::Encoder enc(std::ofstream("out.ogg"));
+    //   TagsEditor editor(options);
+    //   edit_tags(dec, enc, editor);
+    //
     void edit_tags(ogg::Decoder &in, ogg::Encoder &out, TagsHandler&);
 
 }
diff --git a/src/ogg.h b/src/ogg.h
index 14c15a4..5631e47 100644
--- a/src/ogg.h
+++ b/src/ogg.h
@@ -17,6 +17,7 @@ namespace ogg
         DATA_READY,
         RAW_READY,
         END_OF_STREAM,
+        // Meaning of these states below, in Stream.
     };
 
     enum StreamType {
@@ -45,6 +46,20 @@ namespace ogg
         StreamType type;
         Tags tags;
 
+        // Here are the meanings of the state variable:
+        //   BEGIN_OF_STREAM: the stream was just initialized,
+        //   HEADER_READY: the header is parsed and we know the type,
+        //   TAGS_READY: the tags are parsed and complete,
+        //   DATA_READY: we've read a data page whose meaning is no concern to us,
+        //   RAW_READY: we don't even know what kind of stream that is, so don't alter it,
+        //   END_OF_STREAM: no more thing to read, not even the current page.
+
+        // From the state, we decide what to do with the Decoder's current_page.
+        // The difference between DATA_READY and RAW_DATA is that the former
+        // might require a reencoding of the current page. For example, if the
+        // tags grow and span over two pages, all the following pages are gonna
+        // need a new sequence number.
+
         ogg_stream_state stream;
     };