[tor-bugs] #31913 [Core Tor/Tor]: Add more robust Tor API documentation

[Tor Bug Tracker & Wiki]

#31913: Add more robust Tor API documentation
------------------------------+--------------------
     Reporter:  chelseakomlo  |      Owner:  (none)
         Type:  enhancement   |     Status:  new
     Priority:  Medium        |  Milestone:
    Component:  Core Tor/Tor  |    Version:
     Severity:  Normal        |   Keywords:  api
Actual Points:                |  Parent ID:
       Points:                |   Reviewer:
      Sponsor:                |
------------------------------+--------------------
 Currently, Tor's API is not well-documented- adding more rich
 documentation (and ideally a separate how-to technical guide) would be
 helpful for external applications to learn how to embed tor.

 For example, tor_control_socket_t needs documentation.
 https://gitweb.torproject.org/tor.git/tree/src/feature/api/tor_api.h#n60

 Furthermore, it isn't clear what are the tradeoffs between embedding Tor
 or running it as an executable:
 https://gitweb.torproject.org/tor.git/tree/src/feature/api/tor_api.h#n11

 Also, it would be helpful to add additional documentation about how to
 interface with tor once it has been invoked (e.g, reading/writing from the
 control port via SOCKS).
 https://gitweb.torproject.org/tor.git/tree/src/feature/api/tor_api.h#n26

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