Updated doclets for jsdoc3 #281
Conversation
Updated so jsdoc3 parser picks everything up. Added event docs. Lots of documentation content needed...
Changed event docs: Changed userData properties from optional to nullable. Removed optional type from preventDefaultAction properties.
|
New commit, changed event docs... Changed userData properties from optional to nullable. |
Updated creation option defaults (issue #93)
Creation options now documented in a typedef doclet named OpenSeadragon.Options.
New commit... Creation options now documented in a typedef doclet named OpenSeadragon.Options. Cleaner! |
openseadragon.js doc fixups
|
New commit... Doc fixups in openseadragon.js |
| * | ||
| * @property {Number} [minZoomLevel=null] | ||
| * | ||
| * @property {Number} [maxZoomLevel=null] |
There was a problem hiding this comment.
Could you add a little description of these two?
|
This is amazing! You deserve some sort of medal! Seems like this also fixes #92... is that true? One thing: could you add a single-sentence description for each event? Some of them are reasonably self-explanatory, I suppose, but they certainly aren't all. Beyond that, if you're finding more doc issues than you want to tackle here, by all means, file new issues for them. :-) We've got a documentation tag set aside for just such things. |
Yes I believe so! I've got I think 12 more that aren't documented. Working on them.
On my TODO list :) A lot of the missing stuff takes a bit of work if I'm not familiar with the associated code, but most events I have a pretty good idea what's up. |
Remaining creation options - still need descriptions on some. Started event descriptions. Viewer constructor parameters fixed.
|
New commit. Added remaining creation options to the typedef except the page callback (waiting for resolution on issue #285). Started adding event descriptions... Note the Viewer class constructor docs. I tried to leave in the legacy parameters. Do we want those there or just the link to the Options typedef like in the module section? |
|
Coming along nicely. And yes, let's just link to Options from Viewer. |
Likewise. All the above fixed for the next commit, except this one (so far). Good example of why I feel I could spend months in the comments/doclets alone ;) |
Misc changes. Committing to merge upstream changes.
|
Looks great... what's left to do? Are all the event descriptors in? |
Still need to do the rest of the events, only did the Button class and got sidetracked on the jsdoc template :) I also need to go through each source file and make sure everything's getting picked up by the parser, mostly any "$.xxx" references. There's still lots of "TODO"s and missing docs....I can get params and properties in there by name at least but it takes a while to track down their descriptions in unfamiliar code. |
|
Man, you're going to be the world's authority on OpenSeadragon at this rate! For this patch, I definitely want the event descriptions. I'm delighted to have the remaining missing/broken docs sorted out as well, so go for it if you have the energy, or file a follow-up task if you burn out. The OpenSeadragon community thanks you for this great service! |
|
New commit... Lots of changes, most notably event documentation (@event and @fires)
:) Not entirely altruistic... I had great success with the Silverlight MultiScaleImage control with custom tile servers and tile sources for huge bio-medical images, but had to abandon browser plugins. To be able to actually work on this code is awesome, and I get to know it at the same time. I'm porting my SVG/HTML annotation code to an OpenSeadragon plugin (open sourced as OpenSeadragonAnnoHost)...the OpenSeadragonImagingHelper and OpenSeadragonViewerInputHook plugins I already wrote, while handy on their own, provide required functionality to the OpenSeadragonAnnoHost plugin, so they were just the first two stages of my master plan :) I'm totally stoked to be working on OpenSeadragon... |
Found another @fires
|
New commit...stumbled across another undocumented @fires |
|
Awesome. Well, I'm loving all the great work you're doing (and the plugins you're making)! The new commits look good. You'll have to let me know when you consider this patch done. The "needs documentation" bits... is that gaps in your knowledge? |
Yeah, tough one. In Viewer, there's the container, which is a ControlDock (a form element), with the keyboardCommandArea (a textarea element) and the canvas (a div element) layered on top. Note the canvas isn't the Drawer canvas element, just canvas by name. All three have their own MouseTrackers, so the 'canvas-xxx' events come from 2 levels up the z-order from the 'container-xxx' events. Simple ;) I'll figure out a way to document it...
Yes. That whole section has a TODO mentioning need for comments documenting what it does and how. |
|
New Commit... I'm ready to land this one for now. :) I think I got the majority of the existing docs and tried to add as much as I could. |
Botton fixes :)
|
New commit...'Botton' fixes :) |
|
This is a monstrous patch! Wonderful to have all these docs fixed up! |
|
I meant to add a link to the JSDoc 3 documentation in README.md, changing
to
Want a pull-request for that? |
|
Good thought... I've gone ahead and done it: |
|
Cool :) |
Updated so jsdoc3 parser picks everything up.
Added event docs.
Lots of documentation content needed...
Pairs with site-build Pull request 33
Fixes #93 and #111 and #92.