This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
Home Products Support Community News


[Xen-tools] Re: [Xen-devel] [PATCH] rework xen/xm/main.py to be more str

To: Mark Williamson <mark.williamson@xxxxxxxxxxxx>
Subject: [Xen-tools] Re: [Xen-devel] [PATCH] rework xen/xm/main.py to be more straight forward
From: Sean Dague <sean@xxxxxxxxx>
Date: Fri, 5 Aug 2005 11:57:35 -0400
Cc: xen-tools@xxxxxxxxxxxxxxxxxxx, Ian Pratt <m+Ian.Pratt@xxxxxxxxxxxx>
Delivery-date: Fri, 05 Aug 2005 15:56:00 +0000
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
In-reply-to: <200508051636.51634.mark.williamson@xxxxxxxxxxxx>
List-help: <mailto:xen-tools-request@lists.xensource.com?subject=help>
List-id: Xen control tools developers <xen-tools.lists.xensource.com>
List-post: <mailto:xen-tools@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-tools>, <mailto:xen-tools-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-tools>, <mailto:xen-tools-request@lists.xensource.com?subject=unsubscribe>
Mail-followup-to: Mark Williamson <mark.williamson@xxxxxxxxxxxx>, Anthony Liguori <aliguori@xxxxxxxxxx>, xen-tools@xxxxxxxxxxxxxxxxxxx, Ian Pratt <m+Ian.Pratt@xxxxxxxxxxxx>
References: <20050801192216.GA5974@xxxxxxxxxxxxxxxxxxx> <42F38464.1080202@xxxxxxxxxx> <200508051636.51634.mark.williamson@xxxxxxxxxxxx>
Sender: xen-tools-bounces@xxxxxxxxxxxxxxxxxxx
User-agent: Mutt/1.5.6i
On Fri, Aug 05, 2005 at 04:36:51PM +0100, Mark Williamson wrote:
> > 3) Have --help be generated based on the contents of
> > xmlib.__dict__[cmd].__doc__
> >
> > #3 has the nice side-effect of ensuring that xmlib is completely
> > documented which makes xmlib the perfect python interface for management
> > tools.  It would be even nicer if the arguments were expanded instead of
> > passed as a list so the functions could be called in a more natural way.
> >
> > A short help can be autogenerated by only grabbing the first sentence of
> > __doc__.
> This sounds reasonable, although I'm slightly wary of mixing user command 
> docs 
> in programmer API doc strings.

Yes, I 100% agree.  There is a difference between API docs which are
expected to be used by developers that already know what most of the code
does, and user docs.

If you move all the docs into a single place in main.py, then when a
developer goes to update docs for a command (s)he has a screen full of docs for
other commands right there.  What will that developer naturally do?  Look at
the doc on his/her screen and make his/her doc look a lot like the examples

This is really just social engineering of developers, but it really does
help drive to consistency without needed a dedicated editor to go through 50
__doc__ sections and ensure they all use the same terms, abbreviations, etc. 
Otherwise you get a developer saying, "you know, I can explain this better",
and changing it for their command only.  Even if they were right, it now no
longer makes sense in a consolidated scheme.

I think the only way to police the interface help is to make it glaringly
obvious when 2 commands use different abbreviations by sticking them right
next to each other.

> > One thing this would break is abbrevation but I'm quite sure Mark is the
> > only one using them :-)
> I'd rather keep abbreviations - they don't hurt people who don't know they're 
> there and they make it that little bit easier for those who do.  However, if 
> nobody wants to support it, it'll be easy for me to patch my local tools :-)

If abbreviations are specifically called out (not just magically matched) I'd
not be opposed to it.  But each one should be a two or three letter code
only, and specifically named in the documentation as well as in the code.



Sean Dague                                       Mid-Hudson Valley
sean at dague dot net                            Linux Users Group
http://dague.net                                 http://mhvlug.org

There is no silver bullet.  Plus, werewolves make better neighbors
than zombies, and they tend to keep the vampire population down.

Attachment: pgpzNNe2AHvGv.pgp
Description: PGP signature

Xen-tools mailing list