aft.c: Improve documentation of the add command.

[paraslash.git] / aft.c

diff --git a/aft.c b/aft.c
index 19e357525ba88c7b2ccfabafc4d974b73f18fb39..4c5e514309b143ae025dd4d5b64d8934f186c0d9 100644 (file)
--- a/aft.c
+++ b/aft.c
@@ -1441,43 +1441,53 @@ static void save_audio_file_info(HASH_TYPE *hash, const char *path,
 }
 
 /*
-input:
+
+Overview of the add command.
+
+Input: What was passed to the callback by the command handler.
 ~~~~~~
-HS:    hash sister
-PB:    path brother
-F:     force flag given
+HS:    Hash sister. Whether an audio file with identical hash
+       already exists in the osl database.
+
+PB:    Path brother. Whether a file with the given path exists
+       in the table.
+
+F:     Force flag given. Whether add was called with -f.
 
-output:
+output: Action performed by the callback.
 ~~~~~~~
-AFHI:  whether afhi and chunk table are computed and sent
-ACTION:        table modifications to be performed
-
-+---+----+-----+------+---------------------------------------------------+
-| HS | PB | F  | AFHI | ACTION
-+---+----+-----+------+---------------------------------------------------+
-| Y |  Y |  Y  |  Y   | if HS != PB: remove PB. HS: force afhi update,
-|                     | update path, keep afsi
-+---+----+-----+------+---------------------------------------------------+
-| Y |  Y |  N  |  N   | if HS == PB: do not send callback request at all.
-|                     | otherwise: remove PB, HS: update path, keep afhi,
-|                     | afsi.
-+---+----+-----+------+---------------------------------------------------+
-| Y |  N |  Y  |  Y   | (rename) force afhi update of HS, update path of
-|                     | HS, keep afsi
-+---+----+-----+------+---------------------------------------------------+
-| Y |  N |  N  |  N   | (file rename) update path of HS, keep afsi, afhi
-+---+----+-----+------+---------------------------------------------------+
-| N |  Y |  Y  |  Y   | (file change) update afhi, hash, of PB, keep afsi
-|                     | (force has no effect)
-+---+----+-----+------+---------------------------------------------------+
-| N |  Y |  N  |  Y   | (file change) update afhi, hash of PB, keep afsi
-+---+----+-----+------+---------------------------------------------------+
-| N |  N |  Y  |  Y   | (new file) create new entry (force has no effect)
-+---+----+-----+------+---------------------------------------------------+
-| N |  N |  N  |  Y   | (new file) create new entry
-+---+----+-----+------+---------------------------------------------------+
-
-afhi <=> force or no HS
+AFHI:  Whether afhi and chunk table are computed and sent.
+ACTION:        Table modifications to be done by the callback.
+
++----+----+---+------+---------------------------------------------------+
+| HS | PB | F | AFHI | ACTION
++----+----+---+------+---------------------------------------------------+
+| Y  |  Y | Y |  Y   | if HS != PB: remove PB. HS: force afhi update,
+|                    | update path, keep afsi
++----+----+---+------+---------------------------------------------------+
+| Y  |  Y | N |  N   | if HS == PB: do not send callback request at all.
+|                    | otherwise: remove PB, HS: update path, keep afhi,
+|                    | afsi.
++----+----+---+------+---------------------------------------------------+
+| Y  |  N | Y |  Y   | (rename) force afhi update of HS, update path of
+|                    | HS, keep afsi
++----+----+---+------+---------------------------------------------------+
+| Y  |  N | N |  N   | (file rename) update path of HS, keep afsi, afhi
++----+----+---+------+---------------------------------------------------+
+| N  |  Y | Y |  Y   | (file change) update afhi, hash, of PB, keep afsi
+|                    | (force has no effect)
++----+----+---+------+---------------------------------------------------+
+| N  |  Y | N |  Y   | (file change) update afhi, hash of PB, keep afsi
++----+----+---+------+---------------------------------------------------+
+| N  |  N | Y |  Y   | (new file) create new entry (force has no effect)
++----+----+---+------+---------------------------------------------------+
+|  N |  N | N |  Y   | (new file) create new entry
++----+----+---+------+---------------------------------------------------+
+
+Notes:
+
+       afhi <=> force or no HS
+       F => AFHI
 
 */