The wizard-precedence comments restate the code (#1272)

Review of #1257 flagged seven comment blocks that restate the code or narrate the change rather than saying why. This trims them to the house one-line default: a five-line re-listing of httrack.c's query3 answer codes, an aside about where the scenarios abort, wording that called the counter a block size, and a six-line header on `hts_wizard_insert_filters`.

The contract facts stay. The log-echo caller reads back the range the function reports, so the return count and the placement of the inserted filters at the tail of the block are still documented at the declaration.

Comment-only: a whitespace-ignoring diff shows no code change.

Signed-off-by: Xavier Roche <xroche@gmail.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/htsopt.h

@@ -568,12 +568,12 @@ struct httrackp {
      growing it would shift every httrackp field declared after it. */
   void *sitemap_state; /**< hts_sitemap_state*, or NULL. Tail: ABI */
   void *singlefile_state; /**< hts_singlefile_state*, or NULL. Tail: ABI */
-  String host_alias; /**< --host-alias: '\n'-separated "alias[,alias...]=host"
-                          rules folding the hostnames of one site onto a single
-                          canonical host. Tail: ABI */
-  /* Live state, not an option: copy_htsopt must leave it alone. */
+  String host_alias;  /**< --host-alias: '\n'-separated "alias[,alias...]=host"
+                           rules folding the hostnames of one site onto a single
+                           canonical host. Tail: ABI */
   int wizard_filters; /**< count of filters the wizard has inserted, held at the
-                           low indices of the array. Tail: ABI */
+                           low indices of the array. Live state, so copy_htsopt
+                           must leave it alone. Tail: ABI */
 };
 
 /* Running statistics for a mirror. */

src/htsselftest.c

@@ -4467,7 +4467,7 @@ static void wz_seed(httrackp *opt, char **filters, int *filptr,
 }
 
 /* Asserts the array holds exactly `want`, in order, naming the slot that
-   differs: every scenario below aborts through here. */
+   differs. */
 static void wz_holds(char **filters, int filptr, const char *const *want) {
   int i;
 
@@ -4498,10 +4498,8 @@ static int st_wizardinsert(httrackp *opt, int argc, char **argv) {
   opt->filters.filters = &filters;
   opt->filters.filptr = &filptr;
   opt->wizard_filters = 0;
-/* Answers, from httrack.c's question: 0 this link, 1 this directory, 2 the
-   host, 3 the parent, 4 this page only, 5 the directory and below, 6 the host,
-   7 the directory's files, 50 nothing. seeker_up is pinned off, so answer 5
-   takes its directory branch; 264 covers the host one. */
+  /* Answers are httrack.c's query3 codes; seeker_up is pinned off, so answer 5
+     takes its directory branch (tests/264 covers the host one). */
 #define INSERT(n, adr, fil)                                                    \
   hts_wizard_insert_filters(opt, (n), (adr), (fil), HTS_FALSE)
 #define HOLDS(...)                                                             \
@@ -4538,7 +4536,7 @@ static int st_wizardinsert(httrackp *opt, int argc, char **argv) {
     goto done;
   }
 
-  /* the block size indexes one crawl's array, so binding an array empties it */
+  /* wizard_filters indexes one crawl's array, so binding another resets it */
   {
     char **other = NULL;
     int otherptr = 7;
@@ -4550,7 +4548,7 @@ static int st_wizardinsert(httrackp *opt, int argc, char **argv) {
     filters_bind(opt, &filters, &filptr);
   }
 
-  /* and a counter that outlived its array still cannot index past the end */
+  /* a counter that outlived its array still cannot index past the end */
   SEED("-*.zip");
   opt->wizard_filters = 99;
   INSERT(6, "h", "/dir/two.html");

src/htswizard.h

@@ -73,10 +73,9 @@ void hts_wizard_answer_filter(htsbuff *f, int slot, int n, const char *adr,
                               const char *fil, hts_boolean seeker_up);
 
 /* Records the filters answer `n` leaves behind for the link (adr,fil), on top
-   of the wizard's own block at the low indices of opt->filters. Last match
-   wins, so a later answer outranks an earlier one, while the command-line
-   filters sitting above the block outrank every answer. The verdict half is
-   hts_wizard_apply_verdict(). Returns the number inserted, which sit at the
+   of the wizard's block at the low indices of opt->filters: last match wins, so
+   a later answer outranks an earlier one and the command-line filters above the
+   block outrank every answer. Returns the number inserted, which sit at the
    tail of the block, ending at opt->wizard_filters. */
 int hts_wizard_insert_filters(httrackp *opt, int n, const char *adr,
                               const char *fil, hts_boolean seeker_up);

tests/297_engine-wizard-precedence.test

@@ -1,13 +1,12 @@
 #!/bin/bash
 #
+# #1250: last match wins, so the order below is each answer's precedence.
 
 set -euo pipefail
 
 # shellcheck source=tests/testlib.sh
 . "$(dirname "$0")/testlib.sh"
 
-# #1250: last match wins, so the order below is each answer's precedence.
-
 # answering "ignore this link" and then "mirror the whole host" takes it back
 list=$(httrack -O /dev/null -#test=wizardinsert h /dir/one.html 0 6)
 test "$list" = "-h/dir/one.html +h/*" || fail "answer order: got [$list]"