Gentoo Logo

Portage Docstring Specification

Content:

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.
  • (optional) Example usage

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
  • Parameters

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'])
  • Return Values

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.



Print

Page updated July 19, 2006

Summary: This document is meant to serve as a proposal for the documentation of portage code using epytext and custom doc blocks.

Chris White
Author

Marius Mauch
Contributor

Zach Medico
Contributor

Brian Harring
Contributor

Alex Tarkovsky
Contributor

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.