[Yum-devel] Plugin API documentation

[Menno Smits]

Michael Favia wrote:
> I welcome the standardization of of yum source documentation but share 
> the same reservations. From what i see the markup also looks a bit 
> un-uniform in application or use (meaning greater room for customization 
> but also for misuse). Do you have an example of a particular yum method 
> that you might be able to mock up as an example if it isnt any trouble?

Yes, with epydoc there is more than one way to do certain things. For 
example you can describe a function parameter using @param, @arg, 
@parameter or @argument. The resulting output is the same however. I'm 
not sure what the reasoning for these synonyms are. Perhaps for 
compatibility with other documentation systems?

Here's an example. This is YumBase.verifyPkg().

def verifyPkg(self, fo, po, raiseError):
     '''Verify that a downloaded package is what we expect.

     @param fo: Path to the local package file.
     @type fo: string
     @param po: Package object to compare downloaded package file to.
     @type po: PackageObject (or subclass)
     @param raiseError: If True, URLGrabError will be raised if the
         package doesn't pass verification.
     @type raiseError: boolean
     @return: True if package is verified, False otherwise.
     @rtype: boolean
     '''

The type descriptions for parameters and return values are completely 
optional and often unnecessary when the parameter descriptions explain 
the type. You could rewrite the above more concisely without losing 
much/any meaning. For example,

def verifyPkg(self, fo, po, raiseError):
     '''Verify that a downloaded package is what we expect.

     @param fo: Path to the local package file.
     @param po: Package object to compare downloaded package file to.
     @type po: PackageObject (or subclass)
     @param raiseError: If True, URLGrabError will be raised if the
         package doesn't pass verification.
     @return: True if package is verified, False otherwise.
     '''

Here I've only documented the type of the less obvious parameter (po).

You can see the epydoc output for yum/__init__.py at 
http://freshfoo.com/yum/epydoctest/. The output for verifyPkg is at the 
bottom of the doco for YumBase.

> Good documentation can remove the ambiguity from source and provide 
> direction for new hackers in the project. Development time could be 
> wasted if this is pursued too greatly but a relatively small investment 
> can reap great rewards in efficiency for patch submission and create a 
> lower barrier of entry for new [experienced] developers to the project. 
> As a latecomer myself i would appreciate some higher level descriptions. 
> Which format is chosen however is of little consequence to me personally.

I completely agree. I don't mind what's used either as long as we have 
something. epydoc seemed reasonable and that's why I suggested it.

Anyone have any further thoughts on this before I start?

Menno