On Mar 10, 2015, at 7:32, Chris St. Pierre <[email protected]> wrote:
> I've just filed a bug on the confusing wording of help text for the
> secgroup-{add,delete,list}-default-rules? commands:
> https://bugs.launchpad.net/python-novaclient/+bug/1430354
>
> As I note in the bug, though, I'm not sure the best way to fix this. In an
> unconstrained world, I'd like to see something like:
>
> secgroup-add-default-rule Add a rule to the set of rules that will be
> added to the 'default' security group in a newly-created tenant.
>
> But that's obviously excessively verbose. And the help strings are pulled
> from the docstrings of the functions that implement the commands, so we're
> limited to what can fit in a one-line docstring. (We could add another source
> of help documentation -- e.g., `desc = getattr(callback, "help",
> callback.__doc__) or ''` on novaclient/shell.py line 531 -- but that seems
> like it should be a last resort.)
>
> How can we clean up the wording to make it clear that "the default security
> group" is, in fact, not "the 'default' security group" or "the security group
> which is default," but rather another beast entirely which isn't even
> actually a security group?
>
> Naming: still the hardest problem in computer science. :(
I don't think your suggestion for the help text is excessively verbose. There
are already longer help texts for some commands than that, and I think it's
important to accurately explain what commands do. You can use a multiline
docstring to have a longer help text.
Why do you say "the default security group" isn't actually a security group?
The fact that it's per-tenant and therefore not necessarily consistent?
melanie (melwitt)
signature.asc
Description: Message signed with OpenPGP using GPGMail
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
