fixup! Do not inherit from std::iterator.

include/zim/archive.h

@@ -539,11 +539,28 @@ namespace zim
    * from race-condition. It is not threadsafe.
    *
    * An `EntryRange` can't be modified and is consequently threadsafe.
+   *
+   * Be aware that the referenced/pointed Entry is generated and stored
+   * in the iterator itself.
+   * Once the iterator is destructed or incremented/decremented, you must NOT
+   * use the Entry.
    */
   template<EntryOrder order>
   class LIBZIM_API Archive::iterator
   {
     public:
+      /* SuggestionIterator is conceptually a bidirectional iterator.
+       * But std *LegayBidirectionalIterator* is also a *LegacyForwardIterator* and
+       * it would impose us that :
+       * > Given a and b, dereferenceable iterators of type It:
+       * >  If a and b compare equal (a == b is contextually convertible to true)
+       * >  then either they are both non-dereferenceable or *a and *b are references bound to the same object.
+       * and
+       * > the LegacyForwardIterator requirements requires dereference to return a reference.
+       * Which cannot be as we create the entry on demand.
+       *
+       * So we are stick with declaring ourselves at `input_iterator`.
+       */
       using iterator_category = std::input_iterator_tag;
       using value_type = Entry;
       using pointer = Entry*;

include/zim/search_iterator.h

@@ -32,10 +32,30 @@ namespace zim
 {
 class SearchResultSet;
 
+/**
+ * A interator on search result (an Entry)
+ *
+ * Be aware that the referenced/pointed Entry is generated and stored
+ * in the iterator itself.
+ * Once the iterator is destructed or incremented/decremented, you must NOT
+ * use the Entry.
+ */
 class LIBZIM_API SearchIterator
 {
     friend class zim::SearchResultSet;
     public:
+        /* SuggestionIterator is conceptually a bidirectional iterator.
+         * But std *LegayBidirectionalIterator* is also a *LegacyForwardIterator* and
+         * it would impose us that :
+         * > Given a and b, dereferenceable iterators of type It:
+         * >  If a and b compare equal (a == b is contextually convertible to true)
+         * >  then either they are both non-dereferenceable or *a and *b are references bound to the same object.
+         * and
+         * > the LegacyForwardIterator requirements requires dereference to return a reference.
+         * Which cannot be as we create the entry on demand.
+         *
+         * So we are stick with declaring ourselves at `input_iterator`.
+         */
         using iterator_category = std::input_iterator_tag;
         using value_type = Entry;
         using pointer = Entry*;

include/zim/suggestion_iterator.h

@@ -31,11 +31,31 @@ class SuggestionResultSet;
 class SuggestionItem;
 class SearchIterator;
 
+/**
+ * A interator on suggestion.
+ *
+ * Be aware that the referenced/pointed SuggestionItem is generated and stored
+ * in the iterator itself.
+ * Once the iterator is destructed or incremented/decremented, you must NOT
+ * use the SuggestionItem.
+ */
 class LIBZIM_API SuggestionIterator
 {
     typedef Archive::iterator<EntryOrder::titleOrder> RangeIterator;
     friend class SuggestionResultSet;
     public:
+        /* SuggestionIterator is conceptually a bidirectional iterator.
+         * But std *LegayBidirectionalIterator* is also a *LegacyForwardIterator* and
+         * it would impose us that :
+         * > Given a and b, dereferenceable iterators of type It:
+         * >  If a and b compare equal (a == b is contextually convertible to true)
+         * >  then either they are both non-dereferenceable or *a and *b are references bound to the same object.
+         * and
+         * > the LegacyForwardIterator requirements requires dereference to return a reference.
+         * Which cannot be as we create the entry on demand.
+         *
+         * So we are stick with declaring ourselves at `input_iterator`.
+         */
         using iterator_category = std::input_iterator_tag;
         using value_type = SuggestionItem;
         using pointer = SuggestionItem*;