[tor-bugs] #8036 [Stem]: Tweak Stem's documentation (was: stem documentation error for NetworkStatusDocumentV3)

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

 I agree with amj703, and I have a few more tweaks.  (Repeating amj703's
 issue here, so that it doesn't get lost):

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

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

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

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

  - RouterStatusEntries should state exactly what fields the referenced
 "thin" document has and what fields it's missing.  For example, none of
 the entries can possibly contain anything from the status footer, e.g.,
 bandwidth weights.  Maybe the example on the Network Status Documents page
 could list `"print router.document.valid_after"` as valid example and
 `"print router.document.bandwidth_weights"` as invalid example.

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

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