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

[Campbell Barton]

Hi Matt, I see where your coming from.
it is documented that its 'Empty' not 'empty', but not linked..

Agree about using BPy Type names in docs being a bit odd, In cases where 
data can only be accessed from one place maybe just call it Mesh.verts 
or verts - instead of MVertSeq, same go's for Scene.objects

Since we are using iterators more and more we could have a generic 
description somewhere linked to from iter types.

also, Iv seen people use foo.__getitem__(key) because thats how its 
documented, We should probably say that foo[key] is the useual syntax.


Matt Ebb wrote:
> Hi,
> 
> Sorry about the long mail but I thought I'd make a small request for 
> more examples and better organisation in the API documentation based on 
> my experience yesterday at work. I needed to create an Empty at each 
> vertex of a mesh, and thought it would be easy to solve with a simple 
> script. I eventually got it working, but it took a fair bit of hunting 
> through the 2.43 API documentation.
> 
> Looking at the first example on the Object module page gave some hints, 
> but it was very had to see the relationship between the example 
> Blender.Camera.New() (for which there is no corresponding version for 
> empties version) and scn.objects.new() and below, Object.New() which is 
> apparently deprecated. It tells me to use Scene.objects.new() but 
> there's no documentation on how to use that there, and just taking a 
> guess, trying:
> 
> empty = scn.objects.new('empty')    then it gave me an error.
> 
> I ended up using:
> 
> empty = Blender.Object.New('Empty', 'emp')
> scn.link(emp)
> 
> which although is deprecated, was the only clear way I could find to 
> figure it all out and just get the damn thing done quickly.
> 
> I had similar problems with getting the verts in a mesh, on the Mesh 
> module page, it has all these nice looking examples with me.verts.extend 
> and so on, but I couldn't find out what those me.verts etc actually are 
> and how to use them. I ended up just guessing that the .verts were a 
> container for the MVert objects and that I could do something like
> 
> for ve in me.verts:
>     blah
> 
> but that was only because I've been subscribed to this mailing list and 
> remembered the discussions on it.
> 
> 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.
> 
> Also looking back through the pages, I notice now that there is a 
> SceneObjects link under the Scene module which probably would have 
> helped me understand what on earth the scene.objects meant, when used in 
> all those examples in the Object module. Of course I didn't find it, 
> it's equally hidden and with a different name like the MVertSeq one, and 
> worse it's on the Scene page. I want to create an object, so it's 
> reasonable to expect to find that sort of info on the Object page, no?
> 
> So anyway, all and all it was a pretty frustrating experience. One 
> philosophy that I try to stick by in all sorts of work that I do related 
> to user interaction is: "Make simple things easy and complicated things 
> possible", and that wasn't the case here.
> 
> Just trying to do a really simple thing, which ended up being about 5 
> lines of code once I figured it out, was quite difficult to achieve. I 
> bet it wold be even harder for some Joe Schmoe who is less involved in 
> Blender than I am and hasn't seen the discussions on this mailing list 
> for example.
> 
> So to try and make this experience more pleasant, I would propose:
> * If something is being deprecated in favour or some new approved way, 
> you're trying to convince people that it's in their interests to do so. 
> So if it hasn't had the heck documented out of it and there aren't lots 
> of clear, explanatory examples, there's not much of an incentive for 
> people to use it as opposed to the old way.
> * It would be great if each example on the Module pages had a few lines 
> of text not only describing what the script is doing, but also how, and 
> why it is doing things a certain way, and more of this in the comments 
> too rather than just describing what's happening.
> * Important things like the SceneObjects etc should be linked to very 
> prominently on the pages of the modules that they contain. Like on the 
> Object module page: eg. in nice big letters or something "To access, and 
> add to the collection of objects in your scene, use the _SceneObjects 
> blahblah_". There should also be some kind of clear info to show that 
> MVertSeq is me.verts - just call it Mesh.verts in the link for crying 
> out loud! It's totally opaque right now and makes the examples hard to 
> follow and learn more about.
> 
> Anyway, hope this helps give some idea of what it's like for a casual 
> scripter who just wants to get stuff done under a deadline :)
> 
> cheers,
> 
> Matt
> 
> 
> ------------------------------------------
> Matt Ebb . matt at mke3.net . http://mke3.net
> 
> 
> 
> _______________________________________________
> Bf-python mailing list
> Bf-python at projects.blender.org
> http://projects.blender.org/mailman/listinfo/bf-python
> 


-- 
See MetaVR Visuals Used at the Combat Studies Institute
http://www.metavr.com/casestudies/baghdadviews.html

Campbell J Barton

133 Hope Street
Geelong West, Victoria 3218 Australia

URL:    http://www.metavr.com
e-mail: cbarton at metavr.com
phone: AU (03) 5229 0241