[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Docstrings and manuals

From: Eli Zaretskii
Subject: Re: Docstrings and manuals
Date: Mon, 18 Apr 2016 05:30:16 +0300

> Cc: address@hidden, address@hidden, address@hidden
> From: Dmitry Gutov <address@hidden>
> Date: Sun, 17 Apr 2016 22:59:21 +0300
> > IOW, writing a good manual is still a human activity that cannot be
> > easily automated.  Ideally, doc strings should be phrased like
> > reference material, covering all the traits as tersely as possible,
> > while the manual should provide an easier reading with more continuity
> > text and even some explanations why things are the way they are.  At
> > least IMO.
> That sounds fine, and maybe this way is best for the more complex 
> subjects, but in general I'd prefer to see docstrings also written with 
> readability in mind.

This would make them too long ad wordy, something we'd like to avoid,
I think.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]