| [orion-dev] Happy about JS Doc? |
Some of the _javascript_ code in Orion uses JS Doc style comments. Some of the API's are really well documented.
Are you using a particular flavor of JSDoc - this one here http://en.wikipedia.org/wiki/JSDoc ? Can you confirm you're happy with it and have no plan to switch to another format any time soon?
Which data types do you use for the @param { }? Do you have a list somewhere? String, Number, Boolean...
I'm thinking it'd be nice to align our own JS code in RTC to use the same JS Doc used in Orion.
Also, if the data type information is used consistently, it may be used as a hint by future tooling to provide some refactoring/search capabilities similar to JDT in Java code.
Cheers,
Chrix
editor.js has some nice js doc. I wish every js file I've came across in various projects were that well documented, including mine :-)
/**
* Constructs a new key binding with the given key code and modifiers.
*
* @param {String|Number} keyCode the key code.
* @param {Boolean} mod1 the primary modifier (usually Command on Mac and Control on other platforms).
* @param {Boolean} mod2 the secondary modifier (usually Shift).
* @param {Boolean} mod3 the third modifier (usually Alt).
* @param {Boolean} mod4 the fourth modifier (usually Control on the Mac).
*
* @class A KeyBinding represents of a key code and a modifier state that can be triggered by the user using the keyboard.
* @name eclipse.KeyBinding
*
* @property {String|Number} keyCode The key code.
* @property {Boolean} mod1 The primary modifier (usually Command on Mac and Control on other platforms).
* @property {Boolean} mod2 The secondary modifier (usually Shift).
* @property {Boolean} mod3 The third modifier (usually Alt).
* @property {Boolean} mod4 The fourth modifier (usually Control on the Mac).
*
* @see eclipse.Editor#setKeyBinding
*/
eclipse.KeyBinding = (function() {