> I know this would be more tedious, but couldn't this task not be left to > the author of the code? After all, you manually have to code @param, > @see and the other tags yourself, too.
Not exactly. The doc generator doesn't scan for doc comments, it scans for structures that need documentation. So each class, method and parameter is detected - whether or not documented. When the @param attribute in the doc comment is missing, a warning is shown in the documentation. But the parameter is still shown. This approach should also be followed for events. When you allow an optional documentation, then it will be missing in most cases. The event has to be detected, even if there is no documentation at all. > So why not add a tag @listen and @dispatch? > > @listen qx.constant.Event.INTERVAL on each interval event, widget turns > blue in the face > @dispatch qx.constant.Event.LOADED event is dispatched whenever the data > has been loaded An event is not a part of a method. It is a part of a class. Yes, events are fired in methods. But the event listeners are registered at the class. And this is the part that's interesting for the user. The user doesn't care about which method actually fires the event. Considering this, I think events should have their own doc comment. -- All the advantages of Linux Managed Hosting--Without the Cost and Risk! Fully trained technicians. The highest number of Red Hat certifications in the hosting industry. Fanatical Support. Click to learn more http://sel.as-us.falkag.net/sel?cmd=lnk&kid=107521&bid=248729&dat=121642 _______________________________________________ qooxdoo-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
