Skip to content

Instantly share code, notes, and snippets.

@micmath
Created August 31, 2011 13:09
Show Gist options
  • Save micmath/1183504 to your computer and use it in GitHub Desktop.
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
*/
@tstatler
Copy link

tstatler commented Sep 1, 2011

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. The bulltIn:Object syntax would be just as understandable, but I'm biased against the : syntax for reasons I can't articulate.

@micmath
Copy link
Author

micmath commented Sep 1, 2011

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