Here's round 3.  I've striped out the known issues, since everyone
know nows them.  Replaced that missing link, and clarified on the
&quot;give an example&quot; bit.<br><br><div><span class="gmail_quote">On 7/17/06, <b class="gmail_sendername">Chris White</b> &lt;<a href="mailto:chris.chriswhite@...">chris.chriswhite@...</a>&gt; wrote:</span>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div>Hi all,<br>
<br>
I had a discussion yesterday with the folks and #gentoo-portage
regarding API documentation using epydoc and inline custom doc
strings.&nbsp; Attached is a proposal of what I believe
encompasses a majority of the discussion.&nbsp; Suggestions, comments,
etc. are welcome.&nbsp; My standard gentoo account was doing weird
things with mailing list subscriptions, so I'll be using my gmail
account instead.&nbsp; <br></div><div><span class="sg">
<br>
Chris White<br>

</span></div><br clear="all"></blockquote></div><br>

Title: Portage Documentation Proposal
Date: Sun, 16 Jul 2006 05:47:32 UTC
Author: Chris White <chriswhite@g.o>
License: Public Domain

Abstract
==========

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

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.

Specification
================

Portage code will be documented using the epydoc documentation system.  This system was
choosen as both portage developers and those interested in portage API documentation
were familiar with the tool.  It was also choosen as the main implementor (the author)
is comfortable with the system and how to use it.

The custom doc block format is as follows (vercmp is used as an example):

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

This is broken down into the following key pieces:

1. A short one sentence description of what the package does:

	Compare 2 package versions created in L{pkgsplit <pkgsplit>} format.

2. Optional - 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

3. Parameters:
	a. Description of the parameter:

	@param pkg1: package to compare with.

	b. 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>}.

	@type pkg1: list (example: ['test', '1.0', 'r1'])

4. Return Values:
	a. The type of the return value.  Please list all the possible types

	@rtype: None or integer

	b. More verbose description of the values returned.  The numeric list format
	   must be used for more than one return type.
 
	@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.

Links
======

[1] http://epydoc.sourceforge.net/

License
=========

This document is placed under Public Domain