From 351b6f8fd94f55df12a7e22cd4e579a0bb3085e7 Mon Sep 17 00:00:00 2001
From: Matthieu Gautier <mgautier@kymeria.fr>
Date: Thu, 22 Feb 2024 11:09:10 +0100
Subject: [PATCH] fixup! Fix documentation of `getEntryByPath`.

---
 include/zim/archive.h | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/include/zim/archive.h b/include/zim/archive.h
index 34ab0754e..c9833c346 100644
--- a/include/zim/archive.h
+++ b/include/zim/archive.h
@@ -51,6 +51,25 @@ namespace zim
    * An `Archive` is read-only, and internal states (as caches) are protected
    * from race-condition. Therefore, all methods of `Archive` are threadsafe.
    *
+   * Zim archives exist with two different namespace schemes: An old one and the new one.
+   * The method `hasNewNamespaceScheme` permit to know which namespace is used by the archive.
+   *
+   * When using old namespace, user entries may be stored in different namespaces (historically `A`, `I`, `J` or `-`).
+   * So path of the entries contains the namespace as a "subdirectory" : `A/foo.html`, `I/image.png`, ...
+   * All API taking or returing a path expect/will return a path with the namespace.
+   *
+   * When using new namespace, user entries are always stored whithout namespace.
+   * (For information, they are stored in the same namespace `C`. But consider there is no namespace as all API masks it)
+   * As there is no namespace, paths don't contain it: `foo.hmtl`, `image.png`, ...
+   * All API taking or returning a path expect/will return a path without namespace.
+   *
+   * This difference may seems complex to handle but no so much.
+   * As all paths returned by API is consistent with paths expected, you simply have to use the path as it is.
+   * Forget about the namespace and if a path has it, simply consider it a as subdirectory.
+   * The only place it could be problematique is when you already have a path stored somewhere (bookmark, ...)
+   * using a scheme and use it on a archive with another scheme. For this case, the method `getEntryByPath`
+   * has a compatibility layer trying to transform a path to the new scheme as a fallback if the entry is not found.
+   *
    * All methods of archive may throw an `ZimFileFormatError` if the file is invalid.
    */
   class LIBZIM_API Archive
@@ -249,7 +268,7 @@ namespace zim
 
       /** Get an entry using a title.
        *
-       *  Get an entry using its path.
+       *  Get an entry using its title.
        *
        *  @param title The entry's title.
        *  @return The Entry.
@@ -289,6 +308,8 @@ namespace zim
       Entry getRandomEntry() const;
 
       /** Check in an entry has path in the archive.
+       *
+       *  The path follows the same requirement than `getEntryByPath`.
        *
        *  @param path The entry's path.
        *  @return True if the path in the archive, false else.
@@ -393,7 +414,9 @@ namespace zim
 
       /** Find a range of entries starting with path.
        *
-       * The path is the "long path". (Ie, with the namespace)
+       * When using new namespace scheme, path must not contain the namespace (`foo.html`).
+       * When using old namespace scheme, path must contain the namespace (`A/foo.html`).
+       * Contrary to `getEntryByPath`, there is no compatibility layer, path must follow the archive scheme.
        *
        * @param path The path prefix to search for.
        * @return A range starting from the first entry starting with path
@@ -404,7 +427,7 @@ namespace zim
 
       /** Find a range of entry starting with title.
        *
-       * The entry title is search in `A` namespace.
+       * When using old namespace scheme, entry title is search in `A` namespace.
        *
        * @param title The title prefix to search for.
        * @return A range starting from the first entry starting with title