[tor-bugs] #20168 [Core Tor/Tor]: Clarify our #if{n}def by commenting what they are at the #elif/#else/#endif

[Tor Bug Tracker & Wiki]

#20168: Clarify our #if{n}def by commenting what they are at the #elif/#else/#endif
--------------------------+------------------------------
 Reporter:  dgoulet       |          Owner:  cjb
     Type:  enhancement   |         Status:  accepted
 Priority:  Very Low      |      Milestone:  Tor: 0.2.???
Component:  Core Tor/Tor  |        Version:
 Severity:  Trivial       |     Resolution:
 Keywords:  easy, lorax   |  Actual Points:
Parent ID:                |         Points:
 Reviewer:                |        Sponsor:
--------------------------+------------------------------
Changes (by cjb):

 * status:  new => accepted
 * owner:   => cjb


Comment:

 > I'd guess it's straightforward to make it count the number of lines
 between the if/else/elif and their endif, and suppress the output if
 that's fewer than N lines.

 I've done this now.  I'll attach my changes to smartcommenter.vba as well
 as the patch against the Tor source.  Some questions:

 1. I set the minimum number of lines between #if..#endif before
 introducing an comment to be 20.  Should it be larger?  My thinking was
 that 20 lines is about a screenful at default terminal size.

 2. In this stanza:
 {{{
 #ifdef FOO
 ...
 #else /* FOO */
 ...
 #endif /* FOO */
 }}}
   Should the #else comment be FOO, or !(FOO)?

 3. In this stanza:
 {{{
 #ifndef FOO
 ...
 #else /* FOO */
 ...
 #endif /* FOO */
 }}}
   Should the #endif comment be FOO or !(FOO)?

 4. The vim plugin is capable of annotating long braced/indented sections
 too.  Is that attractive?

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