[tor-dev] Stem Sphinx Documentation
karsten at torproject.org
Wed Jun 6 09:20:56 UTC 2012
On 6/6/12 6:48 AM, Damian Johnson wrote:
> Hi Ravi, Beck, and everyone else hacking on stem. I just finished and
> merged a rewrite of our documentation into reStructuredText. The
> results are... very pretty.
Looks really cool!
I looked through the docs and found these minor issues:
- Does ExtraInfoDescriptor support bridge descriptors yet? Those don't
contain a signature, which means that the signature variable shouldn't
be marked as required. Also, there should be a digest() method for
RelayExtraInfoDescriptor and a digest variable for
BridgeExtraInfoDescriptor; the relay descriptor digest is calculated,
whereas the bridge descriptor digest is parsed from the "router-digest"
- Should the conn_bi_direct_* variables be grouped under "Bi-directional
- ServerDescriptor also has a digest() method for both relay and bridge
descriptors. The same reasoning about a digest() method for relays and
a digest variable for bridges applies here, too. In the documentation
of digest(), better talk about "network status entry" instead of "server
- Why does digest() return the base64-encoded digest, not the
hex-formatted one? Network statuses are the only documents in Tor using
base64 (or rather, a variant of it without trailing ='s), so it's easier
to convert those to hex than to convert everything else to base64. Now,
if you switch to hex, you'll only have to decide between lower-case and
upper-case. I think Tor and metrics-lib use upper-case hex in most places.
- address_alt is not bridge-specific, but relays are going to list
additional OR addresses in their descriptors in the near future.
And here are a few typos that I found while reading:
- "fastest querter" -> "fastest quarter"
- "circuits in a deciles" -> "circuits in a decile"
- "doens't conform" -> "doesn't conform"
- "averate rate" -> "average rate"
- "appeard" -> "appeared"
More information about the tor-dev