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

[Campbell Barton]

Ken Hughes wrote:
> 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

For data thats only ever accessed from 1 place I think its fine to name 
it accordingly. noting that its a custom PyType

Maybe something like
"scene.objects (custom type)"
"mesh.verts (custom type)"