[tor-dev] Stem Sphinx Documentation

[Karsten Loesing]

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#module-stem.descriptor.reader

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