r11651@Kushana: nickm | 2006-12-20 12:05:04 -0500

Add a maintainer script and a new make target "make check-docs" to get a quick dump of which options are undocumented where, and which documentation refers to nonexistent options.


svn:r9160

ChangeLog

@@ -31,6 +31,8 @@ Changes in version 0.1.2.5-xxxx - 200?-??-??
       network with hosts called @, !, and #.
     - Add a new address-spec.txt document to describe our special-case
       addresses: .exit, .onion, and .noconnnect.
+    - Add a maintainer script to tell us which options are missing
+      documentation.
 
   o Security bugfixes:
     - Stop sending the HttpProxyAuthenticator string to directory

Makefile.am

@@ -66,6 +66,9 @@ check-spaces:
 		src/common/[^as]*.c                   \
 		src/or/[^et]*.[ch] src/or/t*.c src/or/eventdns_tor.h
 
+check-docs:
+	./contrib/checkOptionDocs.pl
+
 check-logs:
 	./contrib/checkLogs.pl                        \
 		src/*/*.[ch] | sort -n

contrib/checkOptionDocs.pl

@@ -0,0 +1,86 @@
+#!/usr/bin/perl -w
+# $Id
+use strict;
+
+my %options = ();
+my %descOptions = ();
+my %torrcSampleOptions = ();
+my %torrcCompleteOptions = ();
+my %manPageOptions = ();
+
+# Load the canonical list as actually accepted by Tor.
+my $mostRecentOption;
+open(F, "./src/or/tor --list-torrc-options |") or die;
+while (<F>) {
+    next if m!/\[notice\] Tor v0\.!;
+    if (m!^([A-Za-z0-9_]+)!) {
+        $mostRecentOption = lc $1;
+        $options{$mostRecentOption} = 1;
+    } elsif (m!^    !) {
+        $descOptions{$mostRecentOption} = 1;
+    } else {
+        print "Unrecognized output> ";
+        print;
+    }
+}
+close F;
+
+# Load the contents of torrc.sample and torrc.complete
+sub loadTorrc {
+    my ($fname, $options) = @_;
+    local *F;
+    open(F, "$fname") or die;
+    while (<F>) {
+        next if (m!##+!);
+        if (m!#([A-Za-z0-9_]+)!) {
+            $options->{lc $1} = 1;
+        }
+    }
+    close F;
+    0;
+}
+
+loadTorrc("./src/config/torrc.sample.in", \%torrcSampleOptions);
+loadTorrc("./src/config/torrc.complete.in", \%torrcCompleteOptions);
+
+# Try to figure out what's in the man page.
+
+my $considerNextLine = 0;
+open(F, "./doc/tor.1.in") or die;
+while (<F>) {
+    if ($considerNextLine and
+        m!^\\fB([A-Za-z0-9_]+)!) {
+        $manPageOptions{lc $1} = 1;
+    }
+
+    if (m!^\.(?:SH|TP)!) {
+        $considerNextLine = 1; next;
+    } else {
+        $considerNextLine = 0;
+    }
+}
+close F;
+
+# Now, display differences:
+
+sub subtractHashes {
+    my ($s, $a, $b) = @_;
+    my @lst = ();
+    for my $k (keys %$a) {
+        push @lst, $k unless (exists $b->{$k});
+    }
+    print "$s: ", join(' ', sort @lst), "\n\n";
+    0;
+}
+
+subtractHashes("No online docs", \%options, \%descOptions);
+# subtractHashes("Orphaned online docs", \%descOptions, \%options);
+
+subtractHashes("Not in torrc.complete.in", \%options, \%torrcCompleteOptions);
+subtractHashes("Orphaned in torrc.complete.in", \%torrcCompleteOptions, \%options);
+subtractHashes("Orphaned in torrc.sample.in", \%torrcSampleOptions, \%options);
+
+subtractHashes("Not in man page", \%options, \%manPageOptions);
+subtractHashes("Orphaned in man page", \%manPageOptions, \%options);
+
+

doc/TODO

@@ -135,7 +135,11 @@ N     - they don't count toward the 3-strikes rule
         - should there be some threshold of 503's after which we give up?
         - Delay when we get a lot of 503s?
 N     - split "router is down" from "dirport shouldn't be tried for a while"?
-        want a time_t field for got_503_at.
+        We want a field to hold "when did we last get a 503 from this
+        directory server."  Probably, it should go in local_routerstatus_t,
+        not in routerinfo_t, since we can try to use servers as directories
+        before we have their descriptors.  Possibly, it should also go in
+        trusted_dir_server_t.
       - authorities should *never* 503 a cache, and should never 503
         network status requests. They can 503 client descriptor requests
         when they feel like it.
@@ -163,7 +167,7 @@ NR  D Get some kind of "meta signing key" to be used solely to sign
       key, etc.
     - If we haven't replaced privoxy, lock down its configuration in all
       packages, as documented in tor-doc-unix.html
-N   - script to look at config.c, torrc.sample, tor.1.in, to tell us
+    o script to look at config.c, torrc.sample, tor.1.in, to tell us
       what's missing in which and notice which descriptions are missing.
 
   - Docs

src/or/config.c

@@ -1757,6 +1757,31 @@ print_usage(void)
 "See man page for options, or http://tor.eff.org/ for documentation.\n");
 }
 
+/** Print all non-obsolete torrc options. */
+static void
+list_torrc_options(void)
+{
+  int i;
+  smartlist_t *lines = smartlist_create();
+  for (i = 0; _option_vars[i].name; ++i) {
+    config_var_t *var = &_option_vars[i];
+    const char *desc;
+    if (var->type == CONFIG_TYPE_OBSOLETE ||
+        var->type == CONFIG_TYPE_LINELIST_V)
+      continue;
+    desc = config_find_description(&options_format, var->name);
+    printf("%s\n", var->name);
+    if (desc) {
+      wrap_string(lines, desc, 76, "    ", "    ");
+      SMARTLIST_FOREACH(lines, char *, cp, {
+          printf("%s", cp);
+          tor_free(cp);
+        });
+      smartlist_clear(lines);
+    }
+  }
+}
+
 /** Last value actually set by resolve_my_address. */
 static uint32_t last_resolved_addr = 0;
 /**
@@ -2928,6 +2953,11 @@ options_init_from_torrc(int argc, char **argv)
     print_usage();
     exit(0);
   }
+  if (argc > 1 && !strcmp(argv[1], "--list-torrc-options")) {
+    /* For documenting validating whether we've documented everything. */
+    list_torrc_options();
+    exit(0);
+  }
 
   if (argc > 1 && (!strcmp(argv[1],"--version"))) {
     printf("Tor version %s.\n",VERSION);