[Yum-devel] Plugin API documentation

[Michael Favia]

seth vidal wrote:

>On Wed, 2005-03-30 at 23:13 +1000, Menno Smits wrote:
>  
>
>>I'm about to start producing some documentation for yum plugin 
>>developers to use. Ideally this will be mostly generated from the code 
>>via docstrings.
>>    
>>
>Where are the format requirements for epydoc? I looked on the epydoc
>website and they didn't immediately leap out at me.
>
>also does it make the unreadable when just reading the source code?
>  
>
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?

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.

-mf