[tor-bugs] #32211 [Core Tor/Tor]: write description of subsystem initialization/shutdown architecture

[Tor Bug Tracker & Wiki]

#32211: write description of subsystem initialization/shutdown architecture
-------------------------------------------------+-------------------------
 Reporter:  catalyst                             |          Owner:  nickm
     Type:  task                                 |         Status:
                                                 |  needs_review
 Priority:  Medium                               |      Milestone:  Tor:
                                                 |  0.4.3.x-final
Component:  Core Tor/Tor                         |        Version:
 Severity:  Normal                               |     Resolution:
 Keywords:  network-team-roadmap-september,      |  Actual Points:  .2
  s31-docs                                       |
Parent ID:  #29215                               |         Points:
 Reviewer:  catalyst                             |        Sponsor:
                                                 |  Sponsor31-must
-------------------------------------------------+-------------------------

Comment (by nickm):

 Replying to [comment:6 catalyst]:
 > Replying to [comment:3 nickm]:
 > > See branch `ticket32211` for a small first draft here. I imagine that
 more documentation is probably desirable; any guidance would be welcome.
 PR at https://github.com/torproject/tor/pull/1520
 > Thanks! Looks good so far. What areas do you think need more work?

 I don't know, TBH.  I'm hoping that there will be questions I can answer
 more about.

 > We might want to explain why we would want to add new fields in the
 middle of `subsys_fns_t`.

 I don't understand -- as opposed to at the end of it?  Or why we'd add new
 fields at all?


 > In `initialization.dox`, maybe move the reference to `subsys_fns_t`
 closer to the beginning of that paragraph? Maybe like
 >
 > > `subsys_fns_t` describes a subsystem and a set of functions [...] To
 define a subsystem...

 Sounds good.

 > As a minor style nit, do we need to use backslashes for Doxygen commands
 in that places you use them here? I would like us to move towards more
 consistently using at-signs for Doxygen commands.

 I'm okay trying to remember to use @ signs in the future, but I'd rather
 not adopt a rule forcing them without tooling to convert and enforce. Does
 that sound okay?

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