[Bf-python] Feedback: Examples and improvements in documentation needed

[Stephen Swaney]

On Sun, Mar 11, 2007 at 05:30:51PM -0700, Ken Hughes wrote:
> 
> I'm not sure if I'm talking about the same thing, but I'd also like if 
> we can at least come up with a standard name for these 
> sequence/interator classes.  I used MVertSeq because I couldn't think of 
> anything better, and at the time Willian suggested we needed to name it 
> something since it wasn't just a simple iterator (it has its own unique 
> attributes and methods).  But I've written a few different sequence 
> wrappers since then and think I've used a few different names.  I think 
> the one I ended up with last was in the Constraint module, but the 
> difference between the Constraints class (the iter/seq) and Constraint 
> (the actual data) is difficult to see at a quick glance.  I think the 
> SceneObjects class that Campbell came up with for Scene API is better, 
> but has such a clear context (scene access to objects) that maybe it's 
> just unique.

I just noticed this other day, while helping Bassam find something in the 
API docs that we have names like Constraint/Constraints.  A little too
similar and difficult to discriminate for my tastes!

Just thinking out loud (JTOL), maybe something like Foo and FooSeq
for a class and it's iter/sequence might work?  FooList is a little
less of a python weenie name, but it would only apply if the collection
actually had list semantics.


> Maybe the next BSOD could clean up the documentation?  By this summer 
> 2.44 will be out and I assume we'll have a long time until 2.50 is 
> ready, so perhaps we can finalize the design of the updated API and use 
> it as the basis of a documentation rewrite?

It is a pity that documentation is not looked upon as sexy, except to
tech writers.

-- 
Stephen Swaney			
sswaney at centurytel.net