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

 Replying to [comment:7 nickm]:
 > Replying to [comment:6 catalyst]:
 > > 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?
 Yes, as opposed to at the end. Hm, given that this is justifying asking
 people to use named initializers, maybe we should also say that they help
 with code readability when many pointers need to be null? Also, I'm
 guessing that sometimes there are reasons to keep a logical grouping of
 fields together? (I'm pretty sure we're not optimizing for storage layout
 here given the existing order of fields in the structure.)

 > > 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?
 Yes. I'm happy if we adopt a guideline (not requirement) to prefer at-
 signs for Doxygen commands in new Doxygen comments.

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