aft.c: Improve documentation of the add command.

[paraslash.git] / aft.c

diff --git a/aft.c b/aft.c
index c54e6afb3e548f0fca8d16c73212fab741cc1f22..4c5e514309b143ae025dd4d5b64d8934f186c0d9 100644 (file)
--- a/aft.c
+++ b/aft.c
@@ -909,7 +909,9 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
                "%s: %lu\n" /* seconds total */
                "%s: %s\n" /* last played time */
                "%s: %d\n" /* num_played */
-               "%s\n", /* tag info */
+               "%s" /* tag info */
+               "%s: %lu\n" /* chunk time */
+               "%s: %lu\n", /* num chunks */
                filename_lines,
                have_score? status_item_list[SI_SCORE] : "",
                        have_score? ": " : "",
@@ -927,7 +929,9 @@ static int print_list_item(struct ls_data *d, struct ls_options *opts,
                status_item_list[SI_SECONDS_TOTAL], afhi->seconds_total,
                status_item_list[SI_LAST_PLAYED], last_played_time,
                status_item_list[SI_NUM_PLAYED], afsi->num_played,
-               afhi->info_string
+               afhi->info_string,
+               status_item_list[SI_CHUNK_TIME], tv2ms(&afhi->chunk_tv),
+               status_item_list[SI_NUM_CHUNKS], afhi->chunks_total
        );
        if (opts->mode == LS_MODE_MBOX) {
                struct osl_object lyrics_def;
@@ -952,7 +956,7 @@ void make_empty_status_items(char *buf)
                "%s: \n" /* dirname */
                "%s: \n" /* basename */
                "%s: \n" /* score */
-               "%s: \n" /* attributes bitnmap */
+               "%s: \n" /* attributes bitmap */
                "%s: \n" /* attributes txt */
                "%s: \n" /* hash */
                "%s: \n" /* image id */
@@ -1437,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
 
 */