[tor-bugs] #31078 [Core Tor/Tor]: improve docs for config var abstraction

[Tor Bug Tracker & Wiki]

#31078: improve docs for config var abstraction
--------------------------+------------------------------------
 Reporter:  catalyst      |          Owner:  nickm
     Type:  enhancement   |         Status:  assigned
 Priority:  Medium        |      Milestone:  Tor: 0.4.2.x-final
Component:  Core Tor/Tor  |        Version:
 Severity:  Normal        |     Resolution:
 Keywords:  042-should    |  Actual Points:
Parent ID:  #29211        |         Points:  2
 Reviewer:                |        Sponsor:  Sponsor31-can
--------------------------+------------------------------------

Comment (by teor):

 I am happy moving forward with the architecture and documentation as you
 describe.

 I have some opinions about naming. Naming is hard. There are lots of good
 options. And different people may prefer different options.

 We are parsing a config. I wonder if it would help to use standard parsing
 jargon.

 Replying to [comment:8 nickm]:
 >
 > On renaming:
 >
 > typed_var_t could be "c data", a "c object", an "encodeable", a
 "manipulatable".

 This isn't quite a token, because it has a type.
 But it's also doesn't quite feel like a variable, because it can be part
 of a config option's value (rather than the entire value).
 It's implemented as a string and its (possibly binary) equivalent.

 I'd like to consider "field" or "element" or some other term here.
 If there's another appropriate word from parsing, codecs, or protocol
 design, I'd happily use that.

 > struct_member_t could probably become an implementation detail of
 config_var_t.

 +1

 > config_var_t could be an "option", "field", "setting", "member",
 "entry".

 option is the term we use in the rest of the code, so let's stick with
 that, unless you think it will cause confusion.

 > var_type_def_t could be "encoder", "encoding", "codec", "manipulator",
 "manip".

 I think "codec" is close, but it's usually used for binary.
 We're doing serialisation and deserialisation to text - is there a more
 precise term?
 How about "format"?

 > Do any of these sound like good changes?
 >
 > ''Edited to add: left to my own devices, I would rename typed_var to
 c_data, make struct_member more hidden, leave var_type_def alone or rename
 it to c_cfg_codec, and leave config_var alone or rename it to
 cfg_option.''

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