Talin wrote:
> /*
>Plot a point at position x, y.
>'x' - The x-coordinate.
>'y' - The y-coordinate.
> */
> void Plot( int x, int y );
>
> The scanner should note that: 'x' and 'y' are in single-quotes, so they
> probably refer to code identifiers.
or maybe th
[EMAIL PROTECTED] wrote:
> Andrew> In such autogenerated documentation, you wind up with a list of
> Andrew> every single class and function, and both trivial and important
> Andrew> classes are given exactly the same emphasis.
>
> I find this true where I work as well. Doxygen is u
Guido van Rossum wrote:
> On 9/29/06, A.M. Kuchling <[EMAIL PROTECTED]> wrote:
>
>>On Fri, Sep 29, 2006 at 09:49:35AM +0900, [EMAIL PROTECTED] wrote:
>>
>>>What is lost according to him is information about how the elements of
>>>a module work together. The docstrings tend to be narrowly focused
Josiah Carlson wrote:
> "BJörn Lindqvist" <[EMAIL PROTECTED]> wrote:
>>> If there are "rampant criticisms" of the Python docs, then those that
>>> are complaining should take specific examples of their complaints to the
>>> sourceforge bug tracker and submit documentation patches for the
>>> releva
On 9/29/06, BJörn Lindqvist <[EMAIL PROTECTED]> wrote:
> If there are "rampant criticisms" of the Python docs, then those that> are complaining should take specific examples of their complaints to the> sourceforge bug tracker and submit documentation patches for the
> relevant sections. And person
"BJörn Lindqvist" <[EMAIL PROTECTED]> wrote:
> > If there are "rampant criticisms" of the Python docs, then those that
> > are complaining should take specific examples of their complaints to the
> > sourceforge bug tracker and submit documentation patches for the
> > relevant sections. And perso
> If there are "rampant criticisms" of the Python docs, then those that
> are complaining should take specific examples of their complaints to the
> sourceforge bug tracker and submit documentation patches for the
> relevant sections. And personally, I've not noticed that criticisms of
> the Pytho
On 9/29/06, A.M. Kuchling <[EMAIL PROTECTED]> wrote:
> On Fri, Sep 29, 2006 at 09:49:35AM +0900, [EMAIL PROTECTED] wrote:
> > What is lost according to him is information about how the elements of
> > a module work together. The docstrings tend to be narrowly focused on
> > the particular function
Simon Brunning wrote:
> The "How to use this module" sections sound like /F's "The Python
> Standard Library", of which I keep the dead tree version on my desk
> and the PDF vesion on my hard drive for when I'm coding in the pub. It
> or something like it would be a superb addition to the (already
On 9/29/06, Greg Ewing <[EMAIL PROTECTED]> wrote:
> An example of a good way to do it is the original Inside
> Macintosh series. Each chapter started with a narrative-style
> "About this module" kind of section, that introduced the
> relevant concepts and explained how they fitted together,
> witho
Andrew> In such autogenerated documentation, you wind up with a list of
Andrew> every single class and function, and both trivial and important
Andrew> classes are given exactly the same emphasis.
I find this true where I work as well. Doxygen is used as a documentation
generation
On Fri, Sep 29, 2006 at 09:49:35AM +0900, [EMAIL PROTECTED] wrote:
> What is lost according to him is information about how the elements of
> a module work together. The docstrings tend to be narrowly focused on
> the particular function or variable, and too often discuss
> implementation details.
On 29-sep-2006, at 4:24, Greg Ewing wrote:
An example of a good way to do it is the original Inside
Macintosh series. Each chapter started with a narrative-style
"About this module" kind of section, that introduced the
relevant concepts and explained how they fitted together,
without going into
Barry Warsaw wrote:
> There's also the pull between wanting to write reference docs for
> those who know what they've forgotten (I love that phrase!) and
> writing the introductory or "how it hangs together" documentation.
The trick to this, I think, is not to try to make the same
piece of d
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1
On Sep 28, 2006, at 8:49 PM, <[EMAIL PROTECTED]> wrote:
> What is lost according to him is information about how the elements of
> a module work together. The docstrings tend to be narrowly focused on
> the particular function or variable, and too of
[EMAIL PROTECTED] wrote:
> xah lee writes:
>
> > anyway, i've rewrote the Python's RE module documentation, at:
> > http://xahlee.org/perl-python/python_re-write/lib/module-re.html
>
> -1
>
> The current docs could be improved (but not by me, at least not
> today), but I don't consider the g
xah lee writes:
> anyway, i've rewrote the Python's RE module documentation, at:
> http://xahlee.org/perl-python/python_re-write/lib/module-re.html
-1
The current docs could be improved (but not by me, at least not
today), but I don't consider the general direction of Xah's edits
desirable.
Josiah Carlson writes:
> fine). While I have heard comments along the lines of "the docs could
> be better", I've never heard the claim that the Python docs are "lousy".
FYI, I have heard this, recently, from Tom Lord (aka developer of
Arch, rx, guile, etc). Since he also took a swipe at Emac
xah lee <[EMAIL PROTECTED]> wrote:
> There are a lot reports on the lousy state of python docs. I'm not
> much in the python community so i don't know what the developers are
> doing anything about it.
I don't know about everyone else, but when I recieve comments like "the
docs are lousy, fix
There are a lot reports on the lousy state of python docs. I'm not
much in the python community so i don't know what the developers are
doing anything about it.
anyway, i've rewrote the Python's RE module documentation, at:
http://xahlee.org/perl-python/python_re-write/lib/module-re.html
and
20 matches
Mail list logo
