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

[Ken Hughes]

Matt Ebb wrote:

> Today now as I write this email and check the API reference again, I see 
> links such as "MVertSeq / This object provides sequence and iterator 
> access to the mesh's vertices."
> 
> I completely glossed over that yesterday since the words 'sequence and 
> iterator access' mean nearly nothing to me, and it was jammed in with 
> those other classes, and doesn't even have the same name! I'm looking 
> for me.verts, not me.MVertSeq! I was looking for information on the 
> .verts down the bottom with all the other variables that follow the same 
> syntax. me.vertexColors looks like the same sort of thing to me as 
> me.verts and I expected to find them together.

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.

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?

Ken