[tor-bugs] #8036 [Stem]: Tweak Stem's documentation

[Tor Bug Tracker & Wiki]

#8036: Tweak Stem's documentation
--------------------+-------------------------------------------------------
 Reporter:  amj703  |          Owner:  atagar
     Type:  defect  |         Status:  new   
 Priority:  normal  |      Milestone:        
Component:  Stem    |        Version:        
 Keywords:          |         Parent:        
   Points:          |   Actualpoints:        
--------------------+-------------------------------------------------------

Comment(by karsten):

 Replying to [comment:5 atagar]:
 > > I understand that stem ignores the minor version, but isn't this
 information valuable to users? For example, if 1.1 adds a field that gets
 parsed by Stem, knowing whether that field will be in Stem's parsed object
 is useful to users.
 >
 > Yup, it is though I think that it's a little redundant to say what minor
 versions mean on both the metrics site and this table. Patches welcome if
 there's a particular change that you think would benefit these docs.

 See the attached patch.  Please tweak as you see fit.

 > > Personally, I find hex most useful, but anything works as long as it's
 clearly documented. Yes, I can write a patch.
 >
 > I spotted this last week that Thomas' visionion script converts the
 router entry digest to hex so it can be matched against the digest in the
 server descriptors...
 >
 > b2a_hex(a2b_base64("%s==" % (entry.digest, ))).upper()
 >
 > https://github.com/tomlurge/visionion/blob/master/import/import.py#L77
 >
 > That's unfortunate. I'd love to get a patch so we avoid the need for
 this kind of conversion!

 I know.  I wrote that script above. :)  Is `b2a_hex` and `a2b_base64` what
 you'd use, too, or are there other methods that you prefer?

 Are you fine with making sure that all hex strings are upper-case?  (I
 actually didn't check if they already are upper-case.)  Making sure they
 are and documenting it means developers can leave out a redundant upper()
 check in their code.

 > > I don't know if something is misparsed, it's just that the
 documentation isn't correct.
 >
 > Oops! I see what you mean. Fixed in part...
 >
 >
 https://gitweb.torproject.org/stem.git/commitdiff/6c99a28e83490537615de9388484c574aa1b85dd
 >
 > In looking at the spec addition that added 'a' lines
 (https://gitweb.torproject.org/torspec.git/commitdiff/e2aafe8) I have a
 couple questions...
 >
 > 1. Can 'a' lines have non-IPv6 addresses? If they're IPv6-only then we
 can make things a little nicer for our users (and should note it in the
 spec).

 IPv4 addresses are okay, too.  The current Tor code doesn't have IPv4
 addresses in `a` or `or-address` lines, but that can be added at any
 point.

 > 2. It looks like the part where it says "(Only included when the vote or
 consensus is generated with consensus-method 13 or later.)" is wrong. It
 was added in method consensus-method 14.

 What is the second "it" in your sentence?

 > > As a related issue, the family field of descriptors contains
 fingerprints as a hex string but prepended with a '$' (as described in
 dir-spec.txt). stem.descriptor.server_descriptor.ServerDescriptor just
 reads these in, and thus includes the '$'.
 >
 > Unfortunately the family field can contain both fingerprints and
 nicknames, so the '$' is needed to differentiate the two. Mind providing a
 patch for what you would like the docs to say?

 (amj703 said this, not I.)  To make things even more fun, family entries
 can contain fingerprint and nickname at the same time.  And to make things
 even more fun than that, there's one variant for named and one for unnamed
 relays.  Here's how metrics-lib documents the method that returns parsed
 family entries:

 {{{
   /* Return nicknames, ($-prefixed) fingerprints, $fingerprint=nickname,
    * or $fingerprint~nickname tuples contained in the family line of this
    * relay, or null if the descriptor does not contain a family line. */
   public List<String> getFamilyEntries();
 }}}

-- 
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/8036#comment:6>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online