| 1 |
On Mon, Jul 17, 2006 at 03:12:25AM +0900, Chris White wrote: |
| 2 |
> This document is meant to serve as a proposal for the documentation of portage |
| 3 |
> code using epydoc[1] and custom doc blocks. |
| 4 |
|
| 5 |
epytext actually- that's what relies on, and is supported by |
| 6 |
other doc manglers. |
| 7 |
|
| 8 |
|
| 9 |
> 2. Other portage API functions used: |
| 10 |
> |
| 11 |
> Functions used: |
| 12 |
> - L{pkgsplit <pkgsplit>} |
| 13 |
> - L{example <portage.example>} |
| 14 |
|
| 15 |
Bad idea. doc strings rules for doc manglers, the base docstring |
| 16 |
bleeds through to derivative methods iff the prototype hasn't been |
| 17 |
mangled. So... you state in the base method, "I use blah". Now |
| 18 |
you're requiring every derivative to either |
| 19 |
1) rewrite the whole docstring |
| 20 |
2) do replace tricks to slip in their func additions. |
| 21 |
|
| 22 |
#1 sucks, #2 is a good way to wind up with whacky docstrings (rather |
| 23 |
fragile). |
| 24 |
|
| 25 |
|
| 26 |
> Known Issues |
| 27 |
> =============== |
| 28 |
> |
| 29 |
> The following are known issues: |
| 30 |
> |
| 31 |
> 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. |
| 32 |
|
| 33 |
No reason to strip it out- file size isn't going to make a difference |
| 34 |
(the slow bits in terms of imports is forced execution in the module |
| 35 |
loadup, import lookup, and loading chunks of stdlib). |
| 36 |
~harring |
Archives