[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
Re: [tor-bugs] #31078 [Core Tor/Tor]: improve docs for config var abstraction
#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
_______________________________________________
tor-bugs mailing list
tor-bugs@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-bugs