[tor-bugs] #23845 [Core Tor/Tor]: Document a stable tor main function

[Tor Bug Tracker & Wiki]

#23845: Document a stable tor main function
-------------------------------------------------+-------------------------
 Reporter:  hellais                              |          Owner:  nickm
     Type:  enhancement                          |         Status:
                                                 |  merge_ready
 Priority:  Medium                               |      Milestone:  Tor:
                                                 |  0.3.3.x-final
Component:  Core Tor/Tor                         |        Version:
 Severity:  Normal                               |     Resolution:
 Keywords:  tor-mobile, review-group-24, s8-api  |  Actual Points:
Parent ID:  #23684                               |         Points:
 Reviewer:                                       |        Sponsor:
                                                 |  Sponsor8
-------------------------------------------------+-------------------------

Comment (by hellais):

 sbs and I looked into this and agree that it looks good.

 Some minor nitpicks and comments we have are the following:

 * What is the purpose of `tools/tor_runner.c`? We suspect it's some sort
 of test to see if the API works, but were unclear about what it's exact
 purpose (and usage) is.
 * It would be useful to maybe add to the docstring of `tor_run_main`
 explaining how to construct `tor_main_configuration_t`
 * Related to the previous point, it would be useful to document what are
 the "best practices" in terms of initial configuration options to pass to
 `tor_run_main` when used as part of a library (for example, setting
 `OwningControllerProcess` or not). Good pointers can be found in txtorcon:
 https://github.com/meejah/txtorcon/blob/master/txtorcon/controller.py#L76.

 I don't think these are blocking to merging this branch, but if you
 consider these things useful, maybe it would be appropriate to file some
 tickets for them (if you would rather postpone this).

 Thanks for the quick turnaround on this, it's greatly appreciated!

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