[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 nickm):

 Replying to [comment:12 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.

 Good point -- I should add some comments.  It is meant to make a library
 that provides the same API as tor_run_main(), but which launches Tor in a
 separate process, so that you can write code that will work either way.

 > * It would be useful to maybe add to the docstring of `tor_run_main`
 explaining how to construct `tor_main_configuration_t`

 Will do.

 > * 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 think this will have to be a separate ticket.  Many of those ideas
 should IMO become other options that you can set on
 tor_main_configuration_t.

 > 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:13>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online