The motivation behind this proposal was the current lack of standardized documentation for the portage API. This makes it difficult for developers that would like to somehow customize portage, or use the portage API for their own custom scripts.
Portage code will be documented using the epydoc documentation system. This system was chosen as both portage developers and those interested in portage API documentation were familiar with the tool. It was also chosen as the main implementor (the author) is comfortable with the system and how to use it. The following is an example of a docstring for the pkgcmp function:
Code Listing 2.1: Example pkgcmp docstring |
def pkgcmp(pkg1, pkg2):
"""
Compare 2 package versions created in pkgsplit format.
Example usage:
>>> from portage_versions import *
>>> pkgcmp(pkgsplit('test-1.0-r1'),pkgsplit('test-1.2-r3'))
-1
>>> pkgcmp(pkgsplit('test-1.3'),pkgsplit('test-1.2-r3'))
1
@param pkg1: package to compare with
@type pkg1: list (example: ['test', '1.0', 'r1'])
@param pkg2: package to compare againts
@type pkg2: list (example: ['test', '1.0', 'r1'])
@rtype: None or integer
@return:
1. None if package names are not the same
2. 1 if pkg1 is greater than pkg2
3. -1 if pkg1 is less than pkg2
4. 0 if pkg1 equals pkg2
"""
if pkg1[0] != pkg2[0]:
return None
mycmp=vercmp(pkg1[1],pkg2[1])
if mycmp>0:
return 1
if mycmp<0:
return -1
r1=string.atof(pkg1[2][1:])
r2=string.atof(pkg2[2][1:])
if r1>r2:
return 1
if r2>r1:
return -1
return 0
|
Code Listing 2.2: Description |
Compare 2 package versions created in L{pkgsplit <pkgsplit>} format.
|
Code Listing 2.3: Additional Information |
This describes a more complex function. More paragraphs here. |
Code Listing 2.4: Example Usage |
Example usage:
>>> from portage_versions import *
>>> pkgcmp(pkgsplit('test-1.0-r1'),pkgsplit('test-1.2-r3'))
-1
>>> pkgcmp(pkgsplit('test-1.3'),pkgsplit('test-1.2-r3'))
1
|
Description of the parameter
Code Listing 2.5: Parameter Description |
@param pkg1: package to compare with. |
Type of the parameter. An example is required for types with a strict format (format strings, strict lists, etc.). If there are many types that can be given, please gave at most 2. If type is a custom object, it must be referenced to in the format L{name <package.object>}
Code Listing 2.6: Parameter Type |
@type pkg1: list (example: ['test', '1.0', 'r1']) |
The type of the return value. List all possible types returned.
Code Listing 2.7: Return Types |
@rtype: None or integer |
More verbose description of the values returned. The numeric list format must be used for more than one return type, where the types are different and/or the types have a strict format.
Code Listing 2.8: Return Value Description |
@return: 1. None if package names are not the same 2. 1 if pkg1 is greater than pkg2 3. -1 if pkg1 is less than pkg2 4. 0 if pkg1 equals pkg2 |
Existing doc strings will be converted to the new format.
The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.