Add "@sig" for documenting callback signatures?
Broofa
jGrouseDoc" thread. It got me to thinking about listeners and
callbacks, and eventually I diverged enough in what I was thinking
about that I thought I'd spin it off here.]
=== Background ===
One aspect of JavaScript documentation that has always been difficult
is callback functions - functions that an API expects to invoke, but
that the API itself doesn't provide. The qooxdoo listener pattern
from Maria's post is one example. Old DOM-style "onEvent" callbacks
are another, and there are numerous others. In fact, there are
probably a half-dozen or more patterns that make use of a callback in
some form.
At the heart of this problem is the fact that we are currently forced
to treat a callback just like any other variable or function argument
and describe it's type as simply, "Function". For example, here are a
couple possible implementations for a "property change" callback (a
function to invoke if some property of an object changes)...
/**
* Single listener pattern (old DOM-style event handling)
*
* @variable {Function} onPropertyChange
*/
myAPI.onPropertyChange = callbackFunction;
/**
* Multi-listener pattern (new DOM-style event handling)
*
* @param {String} propertyName Property to watch for changes
* @param {Function} callback The function to invoke
*/
myAPI.addPropertyChangeListener = function(propertyName, callback)
{...
What we really want to "say" here is that the callback is a Function
**that should have a specific signature**. But there's no formal way
to do that, so instead we write ad-hoc descriptions in the comment
body (or, more likely, just ignore the problem and hope it goes
away :) ).
Solving this could provide jGD with a significant, unique advantage
over other documentation tools.
=== The @sig Tag ===
By way of a solution, I'll propose an "@sig"(nature) tag, to allow
users to create "signature types" that they can then use elsewhere in
the documentation. For example, the documentation above would
become ...
/**
* Define the property-change callback signature.
*
* @sig {Boolean} PropertyChangeCallback
* @param someObject The object that changed
* @param oldVal The old property value
* @param newVal The new property value
* @returns True to allow the change, false to prevent it
*/
/**
* Single listener (re-documented)
*
* @variable {PropertyChangeCallback} onPropertyChange
*/
myAPI.onPropertyChange = callbackFunction;
/**
* Multi-listener (re-documented)
*
* @param {String} eventName The name of the event
* @param {PropertyChangeCallback} callback The function to invoke
*/
myAPI.addEventListener = function(eventName, callback) {...
I think this has a pretty nice feel to it, but there are a couple
drawbacks I can think of. For starters, it's may be a bit too much
like a programming language for some people's tastes, what with having
to declare and reference these signature types.
Also, it mixes ad-hoc type names into the "real" namespace of the
code. There isn't _actually_ a "PropertyChangeCallback" in the code
anywhere, and this may be confusing.
Finally, I'm not sure how easy it will be to actually generate
documentation that conveys this information well. Unless we reveal
these ad-hoc type names to the reader (which seems like a bad idea),
we'll be forced to show the signature description inline everywhere
it's referenced in the docs.
Those warts aside, this still feels like a pretty good approach to
me. I'm curious what other folks think.
Broofa
/**
* Multi-listener (re-documented)
*
* @param {String} eventName The name of the event
* @param {PropertyChangeCallback} callback The function to invoke
*/
myAPI.addEventListener = function(eventName, callback) {...
... should actually read ...
/**
* Multi-listener (re-documented)
*
* @param {String} propertyName Property to watch for changes
* @param {PropertyChangeCallback} callback The function to invoke
*/
myAPI.addEventListener = function(propertyName, callback) {...
denis.r...@gmail.com
while. The only thing that I don't like is the tag name, but unless
someone would offer a better name we would have to live with it ;-) I
was thinking about "funcdef", but it seems to be as bad as "sig"
Maria, would this functionality address your request or did you mean
something different?
Regards
Denis
Broofa
exactly what these are. See http://en.wikipedia.org/wiki/Method_signature
. In fact, I'd recommend changing this to "@signature". The only
reason I shortened it is that I toyed briefly with having references
to these require a prefix, "sig:", which is easier to type. E.g.
* @variable {sig:PropertyChangeCallback} ...
But I don't think the prefix is necessary.
As for Maria's issue, I think her main concern is with documenting the
argument _values_ (the allowable event names), not the argument
types. I'll reply in-thread over there with further thoughts on
that ...