From 2111e5da5f44ab723b6eba7cea45feb7b5407af6 Mon Sep 17 00:00:00 2001
From: Gouvernathor <44340603+Gouvernathor@users.noreply.github.com>
Date: Fri, 29 Mar 2024 22:44:52 +0100
Subject: [PATCH] Document the diary better

---
 game/scripts/interface/book.rpy | 43 +++++++++++++++++++++------------
 1 file changed, 27 insertions(+), 16 deletions(-)

diff --git a/game/scripts/interface/book.rpy b/game/scripts/interface/book.rpy
index cdacfea4..7e1fe57e 100644
--- a/game/scripts/interface/book.rpy
+++ b/game/scripts/interface/book.rpy
@@ -63,13 +63,15 @@ init python:
     class diary_class(book_readable_class):
         def __init__(self, *args, dictionary, **kwargs):
             """
-            `dictionary` is a dict containing two types of entries:
-            - for normal text pages, id: (title, text).
-                `text` may contain interpolation fields, such as {code}.
-                When that's the case, there must be an 2nd-type entry for "code" in this dict.
-                `title` may be None.
-            - for interpolation codes, code: text.
-                `text` is the text to be used for the interpolation.
+            `dictionary` is a dict containing two kinds of entries:
+            - the first kind is to store the possible pages which can be added to the dict.
+                These entries are the form {str page_id : (str|None page_title, str page_text)}.
+                `page_text` may contain interpolation fields, such as {code}.
+            - the second kind is to store the for interpolation codes to fill in those blanks.
+                These entries are of the form {str interpo_id : str interpo_text}.
+                `interpo_text` is the text to be used for the interpolation.
+
+            See the diary_append method to match interpolation fields with interpolation ids when adding the pages.
 
             Alternatively, `dictionary` may be the name of a store variable containing the actual dictionary
             (that's better when not in a testing phase, for pickling/saving/updating reasons)
@@ -90,18 +92,27 @@ init python:
         def diary_append(self, id, day=None, **branches):
             """
             Adds a page to the diary.
-            `id` is the key of the event that just happened, in the dictionary.
+            `id` is the key of the event that just happened, in the dictionary - a first-kind key.
             `day` sets the day number for the entry, defaulting to the current day.
 
-            `branches` is a dict of {sub-event id : code} for every happened sub-event specializing event `id`.
-            the specified codes will be looked for in the dictionary, and the original entry of id `id`
-            will be formatted by associating {sub-event id} with dictionary[code].
-            If `code` is not a valid entry in the dict, the `code` value itself will be interpolated instead,
-            or nothing if v is a false value (like None).
+            `branches` is a dict of {code : interpo_id} for every happened sub-event specializing the `id` event.
+            The specified interpolation ids will be looked for in the dictionary, and the original entry of id `id`
+            will be formatted by replacing {code} with the text found in dictionary[interpo_id].
+            If `interpo_id` is not a valid entry in the dict, the passed value itself will be interpolated instead,
+            or nothing if it is a false value (like None).
 
-            If the page for the key `id` contains interpolation fields,
-            it is a mistake to not specify all interpolation fields in `branches`.
-            It is benign to specify keys which are not interpolation fields.
+            For example, if the entry associated with "id1549" is ("Tittle", "Today I met {a} and did {b}. I liked it{c}.").
+            Calling `diary_append("id1549", a="Alice", b="nothing", c=" a lot")` will add the page
+            "Today I met Alice and did nothing. I liked it a lot." to the diary, with the title "Tittle".
+            Passing c="" or c=None or c=False will all result in "Today I met Alice and did nothing. I liked it.".
+
+            If the page for the key `id` contains interpolation fields, it is a mistake
+            not to pass all interpolation fields.
+            It is benign to specify keys which are not interpolation fields in the entry : in the previous example,
+            passing d=whatever will not change anything to the result.
+
+            Passing the same page `id` several times will only work the first time, subsequent tries will be ignored.
+            The entry_id attribute (a set) can be accessed, read only, to check if an entry has already been added.
             """
 
             if id in self.entry_ids: