# HG changeset patch
# User Franz Glasner <fzglas.hg@dom66.de>
# Date 1726745281 -7200
# Node ID 398656a289096d52d73afc5fb1b9943d92956e99
# Parent  cd9d5127ade2ee7c78d8ed366eeb4cc9e95495ab
farray.sh: docs

diff -r cd9d5127ade2 -r 398656a28909 share/local-bsdtools/farray.sh
--- a/share/local-bsdtools/farray.sh	Thu Sep 19 13:13:23 2024 +0200
+++ b/share/local-bsdtools/farray.sh	Thu Sep 19 13:28:01 2024 +0200
@@ -63,6 +63,20 @@
 #:   ``_farr_V_<TOKEN>_<INDEX>`` is unexpectedly unset.
 #:   Exceptions to this rule are documented.
 #:
+#: Hints and rules for indexes:
+#:
+#:   For all functions these facts hold:
+#:
+#:   - Every object (array, alist) has a current length LEN.
+#:   - Indexes range from 1 <= INDEX <= LEN.
+#:   - Indexes 0, -1, -2 are evaluated to LEN + given index.
+#:     So `0` indexes the last item, `-1` the second last and `-LEN+1` the
+#:     first item.
+#:   - All index (and length) values must be given as decimal numbers.
+#:
+#:   `null` (aka empty) and/or missing indexes are handled differently in
+#:   the function context.
+#:
 #: Important:
 #:   All names that start with ``_farr_`` or ``__farr_`` are reserved
 #:   for private use in this module.
@@ -644,8 +658,7 @@
 #:                   desired: nothing will be done with the deleted elements.
 #:   $2 (str): The name of the array that is to be spliced
 #:   $3 (int, null): Index, where to remove and/or insert elements.
-#:                   -  `null` is len+1.
-#:                   -  0, -1, -2, ...  -(len-1) are len + given index.
+#:                   A `null` index value is evaluated to `len + 1`.
 #:   $4 (int, null): The length -- the number of elements to delete at given
 #:                   index.
 #:                   If `null` then the length from index to the end of the
@@ -1251,12 +1264,12 @@
 #:   $1 (str): The name of the alist.
 #:
 #: Output (Globals):
-#:   __farr_name (str):
-#:   __farr_token (str):
-#:   __farr_objname (str):
-#:   __farr_keyname (str):
-#:   __farr_valname (str):
-#:   __farr_len (int): The length of the array
+#:   __farr_name (str): The name of the alist.
+#:   __farr_token (str): The token that is the value of the name.
+#:   __farr_objname (str): The variable prefix for the length ("object").
+#:   __farr_keyname (str): The variable prefix for all item keys.
+#:   __farr_valname (str): The variable prefix for all item values.
+#:   __farr_len (int): The length of the alist.
 #:
 #: Exit:
 #:   Iff the array does not exist in some fashion (token and/or storage).