Skip to content

Instantly share code, notes, and snippets.

@micmath
Created August 31, 2011 13:09
Show Gist options
  • Select an option

  • Save micmath/1183504 to your computer and use it in GitHub Desktop.

Select an option

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.
/**
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
*/
@micmath

micmath commented Sep 1, 2011

Copy link
Copy Markdown
Author

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