Add support for @typedef, @callback and @property

[JeffryBooher]

these are pretty tough but here is a simple example of a type:

/**
 * A number, or a string containing a number.
 * @typedef {(number|string)} NumberLike
 */

Here's a radical example (real-use):

  /**
     * Called to get the full path of the view
     * @callback getFullPathCallBack
     * @return {!string} fullPath of the view
     */

    /**
     * Called to get the File object of the view
     * @callback getFileCallBack
     * @return {!File} File object that belongs to the view
     */

    /**
     * Called to change the show or hide the view
     * @callback setVisibleCallBack
     * @param {!boolean} true to show the view, false to hide it
     */

    /**
     * Called to let the view know that it needs to be resized and redrawn
     * @callback resizeToFitCallBack
     * @param {Object=} hint - hint data on how to redraw the view (can be null)
     */

    /**
     * Called to destroy the view object so that it can remove its DOM node from the pane
     * @callback destroyCallBack
     */

    /**
     * Called to determine if the view or child of the view has focus
     * @callback hasFocusCallBack
     * @return {!boolean} true if has focus, false otherwise
     */

    /**
     * Called to inform the view to give focus to its DOM element
     * @callback focusCallBack
     */

    /**
     * Called to get the view's scroll state so that it can be cached and restored later
     * view providers can return any data necessary to restore the scroll position from the cached data
     * @callback getScrollPosCallback
     * @return {*}
     */

    /**
     * Called to restore the scrollPane state and adjust it with a given height delta
     * @callback adjustScrollPosCallBack
     * @param {*} scrollPos - the data cached when getScrollPos was called
     * @param {!number} heightDelta - the height to add to the scroll pos data
     */

    /**
     * Called when a view is moved from one pane to another 
     * @callback switchContainersCallBack
     * @param {jQuery} $container - the new container for the view to move its DOM element in to
     */

    /**
     * Called to get the owning container of a view
     * @callback getContainerCallBack
     * @return {jQuery} the container for the view
     */

    /**
     * View interface
     * @typedef {Object} View
     * @property {getFullPathCallBack} getFullPath 
     * @property {getFileCallBack} getFile 
     * @property {setVisibleCallBack} setVisible 
     * @property {resizeToFitCallBack} resizeToFit 
     * @property {destroyCallBack} destroy 
     * @property {hasFocusCallBack} hasFocus 
     * @property {hasFocusCallBack} childHasFocus 
     * @property {focusCallBack} focus 
     * @property {getScrollPosCallback} getScrollPos 
     * @property {adjustScrollPosCallBack} adjustScrollPos 
     * @property {switchContainersCallBack} switchContainers 
     * @property {getContainerCallBack} getContainer
     */

[JeffryBooher]

I'm not sure how this should be presented. As the documentation suggests, @typedef is used to create ad-hoc classes so in the complex case it could be represented similarly to how we document classes but I primarily use it to show how a callback interface (as shown above) needs to be implemented. Other uses exist as well but generally when specifying an object that is passed in to a function as a set of properties and/or callbacks.

[peterflynn]

+1 on @typedef -- I think that's the most urgent one, since we already use it in several places in our code (e.g. see CSSUtils) and would like to use it more. The others (@callback & @property) seem less important, since we're not actively using them yet and they're not compatible with formal Closure type annotations.

@jbalsas Would it make sense for us to split @typedef out as a separate request, given that?

[jbalsas]

Hey guys, sorry this has been lingering for a while...

I'm looking at the @typedef case... would it make sense to store those definitions and then show for example a tooltip over the custom types with that? (we could also mark custom types somehow to make them different from primitive ones). @callback looks pretty much the same, doesn't it? could be implemented in a similar way...

@JeffryBooher, @peterflynn what do you think?

[JeffryBooher]

tool tips aren't the best affordance. can you make them hyperlinks so that clicking on usage of that type takes you to the typedef? Same with @callback

[jbalsas]

But where should we put and show the @typedefs? It might make sense for the @callbacks, since those will always related to some documented member, but @typedef is pretty much just metadata, not necessarily related to any part of the module...

[jbalsas]

Also... isn't it possible that we could want to use some @typedef definition from a different module than the one we are currently in? Does that seem like a valid use case? In that case, what should we do?

[JeffryBooher]

Can you make a page with just typedefs and callbacks and put them all there as miscellaneous types?

[jbalsas]

Sure... but would you want to jump there from the page you are? Wouldn't you prefer to see what it is in the context of the current module?

[jbalsas]

Maybe a table at the bottom with all used @typedefs in the module with their description...

[JeffryBooher]

oh i like that -- could make it like a disclosure so you can hide/show it like what we do in brackets for inline editors

[jbalsas]

If I understand correctly... you'd like to slide a small table below the typedef when clicking on it with the information? Isn't it pretty much the same as a tooltip?

I was thinking of grouping all used defs together at the bottom (more like a glossary) and make the ones in the docs simple links pointing to those anchors.

What would you prefer?

[JeffryBooher]

when I think table, i think rows and columns (a grid) that doesn't sound very fluid. You can't copy/paste from a tooltip. They generally disappear and it would be better if this were interactive. Links would probably be better than putting in at the bottom but you could do both I suppose. I would prefer them all on their own page though. Some of our class definitions get pretty large.

[peterflynn]

I like the idea of a popover -- in-context like a tooltip, but a little more persistent (e.g. close on click instead of a timeout) and allowing for text selection. Something like the "[1]" / "[2]" / etc. links on this page: http://what-if.xkcd.com/.

[peterflynn]

If we do that though, I think it can be a lightweight thing that just shows the definition for the one typedef that was clicked -- no need to put in a whole table that lists all the typedefs.

[jbalsas]

@peterflynn, yeah, that's what I meant by "tooltip" :smile: We could use a simple popover.

@JeffryBooher would that work for you?

[JeffryBooher]

@jbalsas yeah popover works. I just want to make sure folks can copy/paste :)