[Doc-SIG] epydoc reST markup for stdlib docstrings

[Mary S. Murphy]

Please get your email addresses correct.  I keep getting them. Thanks.
  ----- Original Message ----- 
  From: Michael Foord 
  To: Ralf Gommers 
  Cc: doc-sig at python.org 
  Sent: Wednesday, April 14, 2010 11:22 AM
  Subject: Re: [Doc-SIG] epydoc reST markup for stdlib docstrings


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

  Michael


    Ralf





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

------------------------------------------------------------------------------


  _______________________________________________
  Doc-SIG maillist  -  Doc-SIG at python.org
  http://mail.python.org/mailman/listinfo/doc-sig
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/5a8a7546/attachment-0001.html>