Principles of documentation (was: Python Documentation Blows!)

[Cameron Laird]

.
.
.

better. Maybe it was that year of only really knowing C and C++ that
makes the difference, but I've never had issue with the wxWidgets
documentation.

While I prefer Python's name with description later, having the type of
input and output from the function call given in the function definition
is convenient. Programming with a language that is static typed may be
a pain in the ass, but it is damn convenient when you are looking at
documentation. Even though wxWidgets class definitions can have huge
initialization argument lists, generally you can be sure of what you are
supposed to pass into something, and what you can expect in return.


- Josiah

We're different--always interesting. As a heavy consumer and
producer of documentation, "having the type .. in the function
definition is convenient" intrigues me. Clouding my thoughts
a bit is C's wimpy type system ('love the language, 'recognize
its limits). Your proposition sounds to me much like what we
used to believe about compile-time syntax checking, versus
more robust and application-specific unit tests.

My preliminary reaction, therefore: yes, indeed, type declar-
ations are important, Python documenters should be particularly
careful always to specify them explicitly, and, if anything,
Python has the chance to improve on the standards C and C++ set,
as its typing is stronger.

 

[Josiah Carlson]

We're different--always interesting. As a heavy consumer and

producer of documentation, "having the type .. in the function
definition is convenient" intrigues me. Clouding my thoughts
a bit is C's wimpy type system ('love the language, 'recognize
its limits). Your proposition sounds to me much like what we
used to believe about compile-time syntax checking, versus
more robust and application-specific unit tests.

Goodness, please don't lump me with the compile-time syntax checking
zealots *wink*. I'm talking about convenience in documentation of C/C++
functions; it tells you what you /should/ be passing in. No more, no
less. I find reading such type signatures to be quicker than linguistic
descriptions of the passed arguments.

One really nifty thing about decorators (PEP 318) is that people will
have the option of strong and dynamically typed polymorphism, but the
drawback is that we may get some C++ or Java programmers who use it for
everything, even when it is not necessary or detrimental.

My preliminary reaction, therefore: yes, indeed, type declar-
ations are important, Python documenters should be particularly
careful always to specify them explicitly, and, if anything,
Python has the chance to improve on the standards C and C++ set,
as its typing is stronger.

Agreed.

- Josiah