[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 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.

 > 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 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).

 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.

 > 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?

 Cheers! -Damian

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