On Mon, Jul 17, 2006 at 03:12:25AM +0900, Chris White wrote: > This document is meant to serve as a proposal for the documentation of portage > code using epydoc[1] and custom doc blocks.
epytext actually- that's what relies on, and is supported by
other doc manglers.
> 2. Other portage API functions used:
>
> Functions used:
> - L{pkgsplit <pkgsplit>}
> - L{example <portage.example>}
Bad idea. doc strings rules for doc manglers, the base docstring
bleeds through to derivative methods iff the prototype hasn't been
mangled. So... you state in the base method, "I use blah". Now
you're requiring every derivative to either
1) rewrite the whole docstring
2) do replace tricks to slip in their func additions.
#1 sucks, #2 is a good way to wind up with whacky docstrings (rather
fragile).
> Known Issues
> ===============
>
> The following are known issues:
>
> 1. A large increase in the code size will occur becuase of this. Sugestions
> were made to strip out the docstrings, but it was noted that this would make
> it very difficult to work with tracebacks.
No reason to strip it out- file size isn't going to make a difference
(the slow bits in terms of imports is forced execution in the module
loadup, import lookup, and loading chunks of stdlib).
~harring
pgp9rr97M2pUh.pgp
Description: PGP signature
