Opened 4 years ago

Closed 3 years ago

#14683 closed defect (implemented)

Document medium-scale design of key Tor abstractions

Reported by: nickm Owned by: nickm
Priority: High Milestone: Tor: 0.2.9.x-final
Component: Core Tor/Tor Version: Tor: 0.2.7
Severity: Normal Keywords: tor-doc, 027-triaged-1-in, 028-triaged, tor-docs-dev, tor-doc-modules, nickm-check-done-20160905
Cc: rl1987@… Actual Points:
Parent ID: Points: parent
Reviewer: Sponsor: SponsorU-must

Description

In between the specs and the doxygen documentation, there isn't much to explain _why_ our subsystems work that way, how they fit together, and so on.

Some areas we should really elaborate are:

  • circuits
  • cmux
  • circuitpathbias
  • entrynodes
  • channels
  • the main event loop/connection abstraction

We should probably try to make it a practice to always document new things, and to fill in documentation for older things as we can. Whatever has changed most recently is probably going to be freshest on our minds, so let's start there.

I'm putting this in 0.2.??? as non-blocker, but we should try to get more stuff documented whenever the opportunity exists.

Child Tickets

TicketStatusOwnerSummaryComponent
#19287closednickmDocument how circuitmux worksCore Tor/Tor
#19290closednickmDocument channels in detailCore Tor/Tor
#19291closednickmDocument cell-scheduler and cell-queue stuff in detailCore Tor/Tor
#19292closednickmDocument main event loop actions in detailCore Tor/Tor
#20385closednickmModule documentation for assorted modules, group 1Core Tor/Tor

Change History (24)

comment:1 Changed 4 years ago by rl1987

Parent ID: #12748

comment:2 Changed 4 years ago by rl1987

Cc: rl1987@… added
Parent ID: #12748

comment:3 Changed 4 years ago by nickm

Milestone: Tor: 0.2.???Tor: 0.2.7.x-final

These may be worth looking at for 0.2.7.

comment:4 Changed 4 years ago by nickm

Status: newassigned

comment:5 Changed 4 years ago by nickm

Keywords: 027-triaged-1-in added

Marking more tickets as triaged-in for 0.2.7

comment:6 Changed 4 years ago by isabela

Keywords: SponsorU added
Points: large
Priority: normalmajor
Version: Tor: 0.2.7

comment:7 Changed 4 years ago by rl1987

Parent ID: #12748

comment:8 Changed 4 years ago by nickm

Milestone: Tor: 0.2.7.x-finalTor: 0.2.8.x-final

comment:9 Changed 4 years ago by nickm

Keywords: 028-triaged added

comment:10 Changed 4 years ago by nickm

Keywords: SponsorU removed
Sponsor: SponsorU

Bulk-replace SponsorU keyword with SponsorU field.

comment:11 Changed 3 years ago by nickm

Parent ID: #12748
Severity: Normal

comment:12 Changed 3 years ago by nickm

Milestone: Tor: 0.2.8.x-finalTor: 0.2.9.x-final
Status: assignednew

Turn most 0.2.8 "assigned" tickets with no owner into "new" tickets for 0.2.9. Disagree? Find somebody who can do it (maybe you?) and get them to take it on for 0.2.8. :)

comment:13 Changed 3 years ago by isabela

Sponsor: SponsorUSponsorU-must

comment:14 Changed 3 years ago by nickm

Owner: set to nickm
Status: newaccepted

comment:15 Changed 3 years ago by mikeperry

Keywords: tor-docs-dev added

comment:16 Changed 3 years ago by nickm

Keywords: tor-doc-modules added

comment:17 Changed 3 years ago by isabela

Points: large6

comment:18 Changed 3 years ago by nickm

Points: 6parent

comment:19 Changed 3 years ago by nickm

Owner: nickm deleted
Status: acceptedassigned

comment:20 Changed 3 years ago by nickm

Status: assignednew

Put all unowned "assigned" tickets back into "new".

comment:21 Changed 3 years ago by nickm

Owner: set to nickm
Status: newassigned

comment:22 Changed 3 years ago by nickm

Keywords: nickm-check-done-20160905 added

Batch-tagging a bunch of tickets assigned to me: I believe these are all done or mostly done or done-enough.

comment:23 Changed 3 years ago by nickm

I documented a lot of this stuff in aae034d13e458dfe82b503d3a1b54b0e5200b6b8 ; call it 2 points.

comment:24 Changed 3 years ago by nickm

Resolution: implemented
Status: assignedclosed

This is done as of my october documentation spree

Note: See TracTickets for help on using tickets.