PDA

View Full Version : How to document application wide events using JSDuck



gl-max
20 Sep 2013, 3:27 AM
Hi,

In the sample code below I am creating a controller class. Within the class I am acting on some application wide events. I'd like to document these events, but as they refer to the application rather than MainController I'm a bit uncertain as to where the events should be documented.

Any suggestions?

Thanks,

Max





Ext.define('MyApp.controller.MainController', {
extend: 'Ext.app.Controller',
init: function () {
// Define application wide events.
this.application.addEvents(
/**
* @event
* This is an application event.
* Show the select screen.
*/
'showselectscreen'
);
}
});

ettavolt
21 Sep 2013, 3:46 AM
addEvents is unnecessary. You may place docs on your application class/instance.

gl-max
23 Sep 2013, 6:19 AM
Yes, addEvents is not required.

However, the main point is that the events relate to this.application, and not MainController. So how do you get JSDuck to recognise this. None of the code for this appears in the application class. Surely an event for MainController should be documented differently to an event for "this.application" so that you know they are different.

Max

ettavolt
23 Sep 2013, 7:37 AM
Have you tried to put doc tags in the file with class for "this.application"?

gl-max
23 Sep 2013, 1:03 PM
No, I haven't tried that. In a project with multi-devs none of them would remember to update the docs in that other file so it would end up out of date and a mess, especially when they remove events from the code. Getting people to update the doc comments in one file is hard enough.

I guess what I'm thinking is that there should be some sort of cross reference, where you can see which controllers are firing application events, and which controllers are listening to them. (Similarly for controller events.) Maybe just searching for the event name would be a substitute for a proper cross reference.

Max

ettavolt
24 Sep 2013, 8:50 AM
Well, then they should not fire events on application, because they don't have synchronized knowledge about.
Instead, Ext4.2 supports easy binding to events fired by controllers. They may use unique names and specify * as selector for listen().

Greg Arnott
23 Oct 2013, 6:22 PM
* {@link Class#member link text}

Thus you'd probably enter:



/**
* ...
* The method to {@link Application#addEvents add events} throughout the application.
* ...
*/