[Doc-SIG] epydoc reST markup for stdlib docstrings

[Michael Foord]

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 <mailto: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. We should do real 
usability testing (with 'real' users) if we really want an answer.

Michael

> Ralf
>


-- 
http://www.ironpythoninaction.com/

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