[Doc-SIG] epydoc reST markup for stdlib docstrings

[Ralf Gommers]

On Wed, Apr 14, 2010 at 11:22 PM, Michael Foord
<fuzzyman at voidspace.org.uk>wrote:

>  On 14/04/2010 17:13, Ralf Gommers wrote:
>
>
>
> On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord <fuzzyman at voidspace.org.uk
> > wrote:
>
>>  On 14/04/2010 16:48, Ralf Gommers wrote:
>>
>>  The vertical whitespace vs tags is a taste issue, I agree, from a
>> developer perspective. From a user perspective however, the numpy standard
>> is clearly more readable in a terminal. That's why it looks the way it does.
>> And reading docstrings in a terminal is not a fringe use case by the way.
>>
>>  I would say that reading docstrings in a terminal is the *main* use case
>> - but that is why I tend to value the vertical space highly and personally
>> prefer the less verbose way.
>>
>
> You're a core developer (I think). But for the *average* user, do you
> really think tags are fine? Earlier in this thread there was a mention of
> people that love to read XML. I'm exaggerating a bit of course, but this is
> similar. Whitespace beats tags for readability.
>
>
> Well, docstrings that take up several screens worth of console and scroll
> out of view like merry abandon are horrible.
>

In many cases yes, but that is a totally different issue. The example Nick
posted was 17 lines for numpy standard vs 15 lines for epydoc standard.


> We should do real usability testing (with 'real' users) if we really want
> an answer.
>
> That sounds like a good idea.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/a3b5488e/attachment-0001.html>