[wxPython-dev] SoC Unit Test Status

[Robin Dunn]

Frank Tobia wrote:
> Kevin,
> 
> On 7/11/07, *Kevin Ollivier* <kevino at theolliviers.com 
> <mailto:kevino at theolliviers.com>> wrote:
> 
> 
>     One last question for Frank. I noticed you have an assert for
>     missing wx.Slider.GetRange(). AFAICT, that function is not part of
>     the wx.Slider API. It probably SHOULD be, as we have SetRange(min,
>     max), but right now you get the values by calling GetMin() and
>     GetMax(). It was probably done this way because in C++ returning two
>     values is difficult and they didn't want to use wx.Size or wx.Point
>     for it, so they just stuck with the GetMin/GetMax functions.
> 
> I included that test because of pg.207 in "wxPython in Action": Table 
> 7.10 shows a GetRange function.  Perhaps this should be an erratum?
> 
> This point raises a greater issue.  In the absence of online docs, we 
> can sometimes defer to "wxPython in Action."  In these cases, or in 
> cases where docs and book conflict, which is to be considered canon?  
> Should docs reflect code, and "wxPython in Action" reflect docs?  Should 
> the docs, and the book as well, specify a contract against which the 
> code must conform?  I feel this is an important issue which needs 
> clarification.


I view the book as a (mostly) accurate snapshot of only a subset of 
wxPython functionality that was taken at a specific point in time. 
Therefore it is only "cannon" at that point in time, and only at a high 
level view.  To me it's main purpose is to make the ramp-up time easier 
for newbies and to help more experienced folks get a better grasp of the 
more advanced general concepts like event processing, application 
design, or how to use the more complex things.  However I don't think 
the nitty-gritty details can ever be considered "doctrine" because with 
the nature of the project and community these details would be like 
trying to document the details of a sandcastle in a windstorm.  Since 
that snapshot point in time the library has continued to evolve and 
change, some of which affects things that were documented before 
(although that is usually avoided if possible.)

The C++ docs are closer to being accurate, but they can fall behind 
sometimes and of course there is the issue of not being clear about what 
is available in wxPython.  The wxPython specific docs, while incomplete, 
are probably the closest to being totally accurate since they are 
generated from the actual classes (including the Python-specific things) 
with very little by-hand maintenance.  If some function or method is 
listed there then you know that it actually exists in wxPython and has 
parameters named the same as in the docs.  One of these days I should 
organize a sprint or something for working on filling in the gaps of 
this set of docs.

Of course the ultimate authority is the source code, which IMO is the 
best thing about Open Source Software.

-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!