openstack team mailing list archive
Mailing list archive
Re: documentation of flags, introducing of a naming convention for flags
Thierry Carrez <thierry@xxxxxxxxxxxxx>
Tue, 22 Feb 2011 10:11:52 +0100
Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:184.108.40.206) Gecko/20101208 Thunderbird/3.1.7
Christian Berendt wrote:
> a) we should create a useful documentation including all flags
That's been identified as a necessary area of improvement for doc. I
plan to work on the raw info (organize them in themes and document their
use) and Anne should help me get it into the openstack manual.
It's a bit hard to keep up to date though. Ideally we would autogenerate
it from comments in code...
> b) we should introduce a naming convention for new flags and we should
> rename existing flags
> all flags related to default values are starting with "default_", all
> flags related to a path are starting with "path_".
> Looks like most of the flags have good names at the moment, but I think
> we should write it down in the wiki or the developer documentation to
> reduce the possibility of bad names in the future.
That's definitely something we should do, either in the RST developer
doc or as a CodingStandards subpage in the wiki. Christian: do you take
the lead on that ?
> c) if it's possible we should collect all flags in one file
> At the moment the flags are defined in the files where they are used. I
> think it would be nice to have on file, for example nova/flags.py,
> including all flags used all over the code.
I think there is a rationale for defining some flags locally. If not,
I'd support placing them all in flags.py with a comment about where they
apply, which could serve as a basis for an autogenerated doc.
Thierry Carrez (ttx)
Release Manager, OpenStack