<div dir="ltr"><div>Devs,</div><div><br></div><div>In looking over the new example notebooks (which are great to learn the new features), I see a couple of places that could use a little polish to make them easier to understand, especially for those that aren't expert programmers. For example, taking a look at:</div>
<div><br></div><div><a href="http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/widgets/Part%202%20-%20Events.ipynb">http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/widgets/Part%202%20-%20Events.ipynb</a><br>
</div><div><br></div><div>it would be easy to change:</div><br>print(widgets.Widget.on_trait_change.__doc__)<br><br>to:<div><br></div><div>help(widgets.Widget.on_trait_change)<br></div><div><br></div><div>which actually looks better, is more informative (even for experts), and hides unnecessary implementation details. Another suggestion is to consider hiding the implementational "trait" details. One could use the interface by just thinking in terms of standard Python terms, such as "attribute" or "value".  For example, the code:</div>
<div><br></div>"""<br>def on_value_change(name, value):<br>    print(value)<br>int_range.on_trait_change(on_value_change, 'value')<div>"""</div><div><br></div><div>might be easier to understand if it were:</div>
<div><br></div>"""<br>def callback(name, new_value):<br>    print(name, "changed to", new_value)<br>int_range.on_value_change(callback, 'value')<div>"""</div><div><br></div>
<div>Another reason to consider using the method name "on_value_change" rather than "on_trait_change" is that I'm replicating this API for a different kernel, and the implementation doesn't use "traitlets". Doesn't seem necessary to have this implementational detail show in the UI.</div>
<div><br></div><div>What do you think?</div><div><br></div><div>-Doug</div></div>