[Doc-SIG] epydoc reST markup for stdlib docstrings
ralf.gommers at googlemail.com
Wed Apr 14 17:35:22 CEST 2010
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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Doc-SIG