Hey,
I just find the documentation generally to be often sparse, not
organized that well, and information spread over too many places. It's
not easy to put my finger one what I find wrong with it, but I'll try.
For example, there are lots of pages like this one:
http://manual.qooxdoo.org/devel/pages/desktop/ui_overview.html
Which explain concepts in a somewhat abstract form, but say little about
the actual practical usage. The pages I use use often (and sometimes
have trouble finding) are:
http://manual.qooxdoo.org/devel/pages/widget/widget_ref.html
http://manual.qooxdoo.org/devel/pages/layout.html
But it's subpages only contain very rough descriptions of the widgets,
and no actual code samples either. For some widgets the API viewer has
basic usage sample, but often it doesn't, so you look at the code in the
demo browser to see how they are used (which btw, I just tried to find a
link to the demo browser on the site, and couldn't).
But thast the basic idea we have in our documentation. Keep the stuff in the
manual abstract and see the code samples in the demo browser which offers a
runnable sample of the widget your looking at. And usually, there is always a
cross link from the widget documentation to a demo showing how it is used. If
not, we need to add one because a code sample is often worth a hundred
descriptions.
True, but I'm not sure that that's a choice that needs to be made
necessarily. For starters, I'm not sure if
list.add(new ListItem('item'))
is that much easier than:
model = ['item'];
list = new List(model);
if it is explained well (and considering how confusing I think it
currently is). Even so, and I haven't thought this through to the end,
but even a virtual list could have an add() method and use a "default"
model internally, so the user isn't confronted with it's virtual nature
until that is needed.
In that simple sample, that might be ok even though its missing the neccesary
data array to work. But when it comes to selection or styling or setting
properties of the child widgets or much more, the user just needs to know what
the "virtual" concept means and how it could be solved using data binding.
But even if the virtual widgets remain separate, I think I would
actually prefer them in a separate virtual.* package. Part of the
confusion for me was the namespacing: There is a form.List and a ui.List
- If I build a "form", possibly even using qx.ui.form.Form, do I have to
use form.List? Is list.List inherently unsuitable for use in a form?
Shouldn't I use it together with other widgets from the form.*
namespace? tree.Tree seems to be, in terms of the
namespace-organization, a sibling of list.List, and yet one is virtual,
the other isn't.
Would having the widgets in a separate name space answered these questions? I
don't think that such things can clearly answered by just putting the widgets
in a namespace, at least not when having so many widgets to organize.
I understand the place of the different widgets now, but it still
doesn't feel like a cleanly defined namespace hierarchy. And listen, I
know how it is with APIs that are evolving, and backwards-compatibility,
and I don't have a good solution either. I'm porting a 0.6 app to 1.6,
and so I certainly appreciate any forward-API stability :)
Still, writing this, I did have one potential idea: Because one other
thing that has bothered me with the widgets are the unnecessarily long
package names to access them. For example, to use a Label, I need to
remember it is in qx.ui.basic. If a need a DateChooser, I need to
remember it is in qx.ui.control. Some things are in qx.ui.form, other
have their own subpackages (qx.ui.groupbox) etc. In practice, I often
have to look it up.
Why not use make everything available (and document it as such), as
qx.ui.DateChooser, qx.ui.Label, qx.ui.VBox etc? Internally, it might
still be qx.ui.basic.Label, except the user wouldn't know about it.
If one ever where to decide on a redesign of the namespace/widget
organization, this might offer a way to do this without breaking
backwards-compatibility: Pull the one List, Tree etc. widget that people
are supposed to use into qx.ui.*, but the full names still work.
Offering a API twice doesn't sound reasonable for me. Either we offer it one
way or another. As we have the current API, there need to be good reasons to
change it because it means a lot of work and the benefit would be to have about
50 widgets in one folder. That might be easier to type but much harder to
search trough. And there still might be some cases where you need stuff from
the name spaced world like the table model and so on. Having some kind of
structure offered by the name spaces is currently more worth than having less
to type.
Regards,
Martin
------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
_______________________________________________
qooxdoo-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
