Principles of documentation (was: Python Documentation Blows!)

[Cameron Laird]

In article <c4dpro$5vg$1 at news.service.uci.edu>,
Josiah Carlson  <jcarlson at uci.edu> wrote:
			.
			.
			.
>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.
-- 

Cameron Laird <claird at phaseit.net>
Business:  http://www.Phaseit.net