[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):

 > The API documentation for
 stem.descriptor.networkstatus.NetworkStatusDocumentV3 states that the
 "params" variable has type "list", but it has type "dict".

 Good catch, amj703. Fixed.

 https://gitweb.torproject.org/stem.git/commitdiff/0b1d47d92d447614095cf43fdb35214650db8d82

 > BridgeNetworkStatusDocuments should contain RouterStatusEntryV2s, not
 V3s. Maybe this isn't exactly a documentation issue though.

 Hmmm, I definitely thought they were v3 at the time but I'm not sure
 why...

 https://gitweb.torproject.org/stem.git/commitdiff/b236ac4e0ba830352c447537be6cf59d85650ae0

 Changed...

 https://gitweb.torproject.org/stem.git/commitdiff/7921a46ba8655baa7c4b81d900a9854444675564

 > The Descriptor documentation should state that @type bridge-extra-info
 1.1 is supported, not just 1.0. There's a difference between supporting
 1.0 and ignoring the 1.1 parts and supporting 1.1.

 Please see the bit above:

 "Descriptor types include the following, including further minor versions
 (ie. if we support 1.0 then we also support 1.1 and above)..."

 Stem expects @type annotations to have a minor version, but ignores the
 value. I list minor versions in the table so users can copy and paste them
 for the 'descriptor_type' argument.

 > All fingerprints and digests, which are in most cases 160 bit value
 strings, should state exactly whether they're base64 or lower-case hex or
 upper-case hex encoded.

 Mind writing a patch for this? Personally I scratched my head for quite a
 while trying to figure out what format users would find the most
 convenient for these values.

 > RouterStatusEntries should state exactly what fields the referenced
 "thin" document has and what fields it's missing.

 Hm? The thin document should *only* be missing the routers attribute (as
 documented). Footer attributes like bandwidth_weights should be present.

 > The addresses_v6 field in RouterStatusEntryV3 doesn't support port
 ranges, but only port lists.

 Mind providing an example router status entry that's being misparsed?

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