Improve doc/state-contents.txt

Part of a fix for #40136.

This patch adds all the state file entries to the documentation, and
documents the ones that I understand well.

doc/state-contents.txt

@@ -14,6 +14,21 @@ Recognized fields are:
      Time when this state file was written.
      Given in ISO format (YYYY-MM-DD HH:MM:SS)
 
+
+  MinutesSinceUserActivity (integer)
+  Dormant (0, 1, or "auto")
+
+     These values are used to keep track of how long Tor has been idle,
+     for the purpose of becoming 'dormant' after a long period without
+     any user-initiated requests.
+
+     "MinutesSinceUserActivity" is the number of minutes since the last
+     time the user asked us to do something.  It is set to zero if we're
+     dormant.
+
+     "Dormant" is 1 if Tor was dormant when it wrote its state file, 0 if
+     Tor was active, and "auto" if Tor was starting for the first time.
+
   AccountingBytesReadInInterval     (memory unit)
   AccountingBytesWrittenInInterval  (memory unit)
   AccountingExpectedUsage           (memory unit)
@@ -36,26 +51,6 @@ Recognized fields are:
      BytesAtSoftLimit.  If we hit the soft limit already, we did so at
      SoftLimitHitAt.
 
-  EntryGuard
-  EntryGuardDownSince
-  EntryGuardUnlistedSince
-  EntryGuardAddedBy
-
-      These lines form sections related to entry guards.  Each section
-      starts with a single EntryGuard line, and is then followed by
-      information on the state of the Entry guard.
-
-      The EntryGuard line contains a nickname, then an identity digest, of
-      the guard.
-
-      The EntryGuardDownSince and EntryGuardUnlistedSince lines are present
-      if the entry guard is believed to be non-running or non-listed.  If
-      present, they contain a line in ISO format (YYYY-MM-DD HH:MM:SS).
-
-      The EntryGuardAddedBy line is optional.  It contains three
-      space-separated fields: the identity of the entry guard, the version of
-      Tor that added it, and the ISO time at which it was added.
-
   TransportProxy
 
      One or more of these may be present.
@@ -65,41 +60,137 @@ Recognized fields are:
      this information to spawn pluggable transport listeners in the
      same IP address and TCP port even after tor client restarts.
 
-  BWHistoryReadEnds           (ISO time)
-  BWHistoryReadInterval       (integer, number of seconds)
-  BWHistoryReadValues         (comma-separated list of integer)
-  BWHistoryReadMaxima         (comma-separated list of integer)
-  BWHistoryWriteEnds
-  BWHistoryWriteInterval
-  BWHistoryWriteValues
-  BWHistoryWriteMaxima
-  BWHistoryDirReadEnds
-  BWHistoryDirReadInterval
-  BWHistoryDirReadValues
-  BWHistoryDirReadMaxima
-  BWHistoryDirWriteEnds
-  BWHistoryDirWriteInterval
-  BWHistoryDirWriteValues
-  BWHistoryDirWriteMaxima
-
-     These values record bandwidth history.  The "Values" fields are a list, for
-     some number of "Intervals", of the total amount read/written during that
-     integer.  The "Maxima" are the highest burst for each interval.
+  BWHistory___Ends           (ISO time)
+  BWHistory___Interval       (integer, number of seconds)
+  BWHistory___Values         (comma-separated list of integer)
+  BWHistory___Maxima         (comma-separated list of integer)
+
+     These values record bandwidth history.  The "Values" fields are a list,
+     for some number of "Intervals", of the total amount read/written during
+     that integer.  The "Maxima" are the highest burst for each interval.
 
      Interval duration is set by the "Interval" field, in seconds.  The
      "Ends" field is the ending time of the last interval in each list.
 
-     The *Read* and *Write* fields are the total amount read and
-     written; the *DirRead* and *DirWrite* variants are for directory
-     traffic only.
+     Recognized values for "___" are:
+         Read -- total bytes read
+         Write -- total bytes written
+         DirRead -- total bytes read for directory connections.
+         DirWrite -- total bytes written for directory connections.
+         IPv6Read -- total bytes read on IPv6 connections
+         IPv6Write -- total bytes written on IPv6 connections
 
   LastRotatedOnionKey
 
      The last time that we changed our onion key for a new one.
      Given in ISO format (YYYY-MM-DD HH:MM:SS)
 
+     This field is used to ensure that onion key rotations happen with the
+     appropriate frequency.
+
   TotalBuildTimes
   CircuitBuildAbandonedCount
   CircuitBuildTimeBin
+  BuildTimeHistorgram
 
       XXXX writeme.
+
+  Guard [key=value] [key=value]...
+
+      Describes a single entry guard used by the client.  Key=value
+      entries with unrecognized keys are persisted.  Order is not
+      significant.  For more information about terminology used here,
+      system, see guard-spec.txt in the tor specifications repository.
+
+      Recognized keys are:
+
+         in (string)
+
+              The name of a guard selection that this guard is in.
+
+         rsa_id (string)
+
+              RSA fingerprint of this guard, without spaces.
+
+         nickname (string)
+
+              Declared nickname of this guard.
+
+         sampled_on (Time in ISO YYYY-MM-DDTHH:MM:SS format)
+
+              When was this guard added to the Guard sample?
+
+         sampled_by (tor version)
+
+              Which version of Tor added this Guard to the sample?
+              (Used to help with debugging.)
+
+         sampled_idx (integer)
+
+              Index of this guard among sampled guards.
+
+         listed (boolean)
+
+              Did this guard appear in the most recent consensus?
+
+         unlisted_since (Time in ISO YYYY-MM-DDTHH:MM:SS format)
+
+              If this guard is not listed, when is the earliest
+              consensus in which we found it unlisted?
+
+         confirmed_on  (Time in ISO YYYY-MM-DDTHH:MM:SS format)
+
+              When did this guard become confirmed?
+
+         confirmed_idx (integer)
+
+              Index of this guard among confirmed guards.
+
+         bridge_addr (address)
+
+              If this guard is a bridge, its current address.
+
+         pb_use_attempts
+         pb_use_successes
+         pb_circ_attempts
+         pb_successful_circuits_closed
+         pb_collapsed_circuits
+         pb_timeouts
+
+
+Obsolete fields include:
+
+  EntryGuard
+  EntryGuardDownSince
+  EntryGuardUnlistedSince
+  EntryGuardAddedBy
+
+      These lines formed sections related to entry guards.  Each section
+      starts with a single EntryGuard line, and is then followed by
+      information on the state of the Entry guard.
+
+      The EntryGuard line contains a nickname, then an identity digest, of
+      the guard.
+
+      The EntryGuardDownSince and EntryGuardUnlistedSince lines are present
+      if the entry guard is believed to be non-running or non-listed.  If
+      present, they contain a line in ISO format (YYYY-MM-DD HH:MM:SS).
+
+      The EntryGuardAddedBy line is optional.  It contains three
+      space-separated fields: the identity of the entry guard, the version of
+      Tor that added it, and the ISO time at which it was added.
+
+      EntryGuardPathBias and  EntryGuardPathUseBias are superseded by
+      the `pb_...` elements in the Guard flag, and served a similar purpose.
+
+      These entries have all been superseded by the Guard line type,
+      since Tor 0.3.0.1-alpha.
+
+  HidServRevCounter
+
+      It was once used to ensure that v3 onion service directory revision
+      numbers were strictly increasing; we now use an order-preserving
+      encryption scheme for that purpose.
+
+      This option could appear multiple times; each time it does, it
+      applies to a different hidden service.