Til Schneider schrieb:
> In another dicussion thread the request for showing events in the API
> documentation came up again.
>
> Some time ago, I created a bug report
> (http://bugzilla.qooxdoo.org/show_bug.cgi?id=96) hoping to start a
> discussion about how this feature could be added the best way. It seems
> that discussions work much better on the mailing list. So I'm trying no
> to move the discussion here again.
>
> Everyone who wants to discuss about this issue: Please read the bug
> report first. It makes some suggestions that don't need to be repeated
> over and over again.
>
>
> My opinion is the following: Documentation about events should be added
> very soon. So as a first step the doc generator should be able to detect
> documented events. As a second step the doc generator should be able to
> detect undocumented events. This task is a lot more complicated as shown
> in the bug report. Nevertheless it is IMO vital for a good documentation
> for two reasons:
> 1. All events show up in the documentation. So people could use them
> even when they're not documented.
> 2. A warning could be added to the documentation, showing that
> documentation is missing.
>
>
> But how should this be done? Introducing a defineEvent-method is no real
> option since it takes runtime performance. This means events should be
> detected by the calls of dispatchEvent. Putting the event documentation
> to these calls leads to many problems since events could be thrown in
> multiple places. Or several event types could be thrown at the same place.
This double definition is also a problem for functions. For example
functions which are declared inside a browser-switch. I don't think this
is a problem.
In my opinion the documentation system should:
* mention the event types (each one only once)
* use the first doc comment for documenting this event (like in
functions already done - hopefully)
I think events should also be defined were the dispatch occurs. Like
functions are documented, where the function is defined. I don't think
we need to break these concept for events.
>
> That's why I would propose to document events in the doc comment of the
> class. Since for the user it is the class that throws events and where
> event listeners have to be registered.
>
> An example:
> ----- snip -----
> /**
> * This is the main widget, all visible objects in the application
> * extend this.
> *
> * @event appear Thrown when the widget appears.
> * @event dispose Thrown the the widget is disposed.
> */
> qx.OO.defineClass("qx.ui.core.Widget", qx.core.Target,
> ...
> ----- snap -----
To keep the events in a central place also makes it more complicated to
keep it up-to-date with the documentation. Is much easier to do this in
my opinion:
----- snip -----
qx.Proto.doSomething = function()
{
[...]
/**
* @event load Throw when data is loaded.
*/
this.createDispatchEvent("load");
}
----- snap -----
>
>
> This should be sufficient for the first step. The next step - detecting
> dispatchEvent-calls - is more complex, since it's not easy to extract
> the event name, because often constants are used. Perhaps we have move
> the event name from the event itself to a parameter of the
> dispatchEvent-method. And perhaps we have to define a way how the
> constants have to be named, so their value could be extracted from their
> name...
What's about to just ignore the event type defined in the script source
and also use the name defined by the doc comment? Maybe the general
cases could also be easily implemented to be detected automatically.
Constants for example already seems to work inside the properties etc.
Cheers,
Sebastian
>
>
>
>
> -------------------------------------------------------------------------
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to share your
> opinions on IT & business topics through brief surveys -- and earn cash
> http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> qooxdoo-devel mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys -- and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
qooxdoo-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
