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 <pyt...@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
pgp5hKpiCAPC2.pgp
Description: PGP signature
