Created
August 31, 2011 13:09
-
-
Save micmath/1183504 to your computer and use it in GitHub Desktop.
Three proposals for a syntax to allow documenting symbols attached to JavaScript built-ins.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/** | |
Encrypt this string. | |
@function crypt | |
@member {@builtin String}.prototype | |
@see {@link {@builtin String}} | |
@param {string} salt | |
*/ | |
String.prototype.crypt = function(salt) { | |
} | |
/** | |
Reduce this array to a few random members. | |
@function few | |
@member builtin:Array.prototype | |
@see {@link builtin:Array} | |
@param {int} [howmany] | |
*/ | |
Array.prototype.few = function(howmany) { | |
} | |
/** | |
An extension to Object. | |
@function keys | |
@member [[Object]].prototype | |
@see {@link [[Object]]} | |
@returns {Array<string>} The names of the properties of this object. | |
*/ | |
Object.prototype.keys = function() { | |
} | |
/** | |
@function columnise | |
@param {{@builtin String}#PlaceHolder} spliton | |
*/ | |
/** | |
@function createReport | |
@param {builtin:Array#Hash} data | |
*/ | |
/** | |
@function serialise | |
@param {[[Object]]#Reader} binaryStream | |
*/ |
There is already precedence in JSDoc2 for the : syntax with event:foo
, and in JSDoc3 with module:foo
so it is consistent to use the same syntax with builtins. It has been pointed out that the user might not be extending something built in, but rather may be extending any object defined elsewhere, like jQuery.fn
. So I think the actual syntax may be external:Object
and external:"jQuery.fn"
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
I like the
@builtin
syntax. The double square bracket syntax is more concise, but I think having a tag would be more discoverable and immediately understandable. ThebulltIn:Object
syntax would be just as understandable, but I'm biased against the : syntax for reasons I can't articulate.