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!
Karsten http://www.atagar.com/transfer/tmp/stem_html_12_06_05/stem.descriptor.html#m...
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" line.
- Should the conn_bi_direct_* variables be grouped under "Bi-directional connection usage:"?
- 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 descriptor entry".
- 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"
Best, Karsten