Re: epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 11:22 PM, Michael Foord
<[email protected]>wrote:

>  On 14/04/2010 17:13, Ralf Gommers wrote:
>
>
>
> On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord <[email protected]
> > 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

_______________________________________________
Doc-SIG maillist  -  [email protected]
http://mail.python.org/mailman/listinfo/doc-sig