Portage Docstring Specification
1.
Introduction
Motivation
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.
2.
Implementation
Specification
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
|
Docstring Breakdown
- A short one sentence description of what the package does
Code Listing 2.2: Description |
Compare 2 package versions created in L{pkgsplit <pkgsplit>} format.
|
-
(optional) Any additional paragraphs required to describe the function in
more detail
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
|
Backwards Compatibility
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.
|
