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

[Sean Dague <sean@xxxxxxxxx>]

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
there.

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

-- 
__________________________________________________________________

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: pgptx87t0RCiE.pgp
Description: PGP signature

_______________________________________________
Xen-tools mailing list
Xen-tools@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-tools