Re: [gentoo-dev] python-namespaces.eclass

[Brian Harring <ferringb@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2104 bytes --]

On Sat, Apr 30, 2011 at 11:27:47PM +0200, Arfrever Frehtes Taifersar Arahesis wrote:
> 2011-04-04 13:48:43 Brian Harring napisał(a):
> > > # @ECLASS: python-namespaces.eclass
> > > # @MAINTAINER:
> > > # Gentoo Python Project <python@gentoo.org>
> > > # @BLURB: Eclass for packages installing Python namespaces
> > > # @DESCRIPTION:
> > > # The python-namespaces eclass defines phase functions for packages installing Python namespaces.
> > 
> > ^^^ This isn't a useful description.
> 
> IMHO it's sufficient, but could you suggest some sentences of description?

It probably is sufficient for *you*- you're knee deep in the guts of 
python, and know it's purpose.  Plus you wrote the eclass ;)

The purpose of the description, and general code comments is for 
*other* folk who may be looking at that code/problem for the first 
time.  It needs to be written aimed at them.

I'd suggest doing a grep of DESCRIPTION w/in eclasses and working from 
the clearer examples- just looking at the first few examples returned, 
alternatives for example has enough in the opening description to 
understand exactly what it's for, same for apache-2.

One thing to keep in mind is that even for folk who know python, this 
is actually an area that doesn't match the normal verbage, and is a 
bit niche in it's usage- try googling 'python namespaces' sometime, 
note that it's scope discussions rather than pkgutil/distribute 
importation across multiple directories. 

To be clear, 'python namespaces' is a whole other thing from what this 
is doing- this is manipulation of importation pathways (the 
module/import hierarchy/namespace, rather than the common scope 
terminology).

Either way, rough suggestion:
"""
This eclass handles installation/creation of python 2.7 and higher 
pkgutil namespaces, and the equivalent distibute functionality.  See 
zope's (example ebuild) for examples of usage.
"""

Rewording it might be wise, but that lays out exactly what this is 
for, it's intended usage, and gives folks a pointer were to look for 
usage examples.
~brian

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]