Re: epydoc reST markup for stdlib docstrings
Ralf Gommers <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Message-ID | <[email protected]> |
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. Ralf _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig