Skip to content

Improve top-level arti-client documentation, add example code

eta requested to merge eta/arti:improve-client-docs into main

This overhauls the top-level arti-client documentation significantly:

  • the "Using arti-client" section walks the user through all of the necessary steps to initiate a Torified TCP connection, and then provides a code example
    • this example is also available as examples/readme.rs; it's not run as a doctest, since it involves connecting to Tor
    • a "More advanced usage" subheading provides information about stream isolation (and can potentially be used for other interesting features once we get them).
  • a new "Multiple runtime support" section was added to explain the purpose and usage of the tor-rtcompat crate
  • the section on design and privacy considerations was removed; this is probably okay to keep in a README, but users of the crate aren't going to be interested in this (at least I don't think)

(also, the doc comment for arti_client::Error was fixed to make actual sense)

Things to think about as a reviewer

  • Is it okay to divorce the README and top-level crate documentation? If so, an exception should probably be added to the script that syncs the two.
  • Do the docs seem to flow naturally and make sense? Are they too detailed, and could more of them be moved into module-level documentation?
  • Is the example useful for understanding the crate? Does it need to be more or less verbose?

also, I strongly recommend actually viewing the docs rendered in rustdoc; don't just use the gitlab changes view (I can probably give you an HTML file if you want one)

Edited by eta

Merge request reports