Add support for JS global objects documentation linking

[ixti]

It should recognize global objects in the returned values

/**
 *  Foo.bar(a) -> Array
 **/

The above, should replace Array with link to Array documentation.

It should recognize global objects in the arguments definition

/**
 *  Foo.bar(a) -> Array
 *  - a (RegExp): Some description
 **/

The above should replace RegExp with link to RegExp documentation

It should recognize global objects in links

/**
 *  Foo.baz -> String
 *
 *  Serialized representation of self as [[Object]].
 **/

The above should replace [[Object]] with link to Object documentation

By default links to global objects should point MDN. But there should be an option to provide custom URL for global objects documentation (e.g. node.js documentation page).

[Sannis]

What do you think about references to Node.js classes?

[ixti]

I think it should be MDN by default. Here's some extra points that should be considered:

• allow provide "custom" link format, e.g. http://mydocs.com/js/{name}.html
• allow provide a way to link format for own "well-known" object, e.g. I want [[Mincer]] to point mincer's documentation.
• have built-in presets of well known names

I propose to have argument named well-known with ability to specify it multiple time. Format of value should be: <alias>|<names>=<link_fmt>.

• <alias>: A simple identifier of built-in presets, e.g. @mdn, @node.
• names: Comma separated list of names, e.g. Object,Array,...
• link_fmt: Link format for given list of names, e.g. https://mydocs.net/js/{name}.html

According to above:

• --well-known @mdn equals --well-known Object,Array,...=https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/{name}
• --well-known @node equals --well-known Buffer,path,...=http://nodejs.org/api/{name:downcase}.html

So it should allow us specify multiple well-known names: --well-known @mdn --well-known @node. Notice that we need to implement filters for variables interpolations (at least downcase and capitalize).

[Sannis]

Format of value should be: [[<names>=]<link_fmt>].

'=' is bad IMO: --well-known=Object,Array=http://whetever.com/jsdocs/{name}.html breaks my brain.

[ixti]

Sorry - I have updated my proposal. I might agree about =. Probably we can use @ symbol:

--well-known @mdn
--well-known Buffer,path@http://nodejs.org/api/{name:downcase}.html

[Sannis]

I have idea about some usage of : or ;, but you have a better catch.

[ixti]

I thought about :, but it's quiet ugly Buffer,path:http://.... And ; will force to either escape it or take argument into quotes.

[puzrin]

Why not just use file with simple words mapping?

--references mapping.txt

File content:

Array http://...
Object http://...
Buffer http://

We can attach some default files, or user can use custom one.

Also, that can be added in .ndocrc (1 line per link), since argparse supports appendeable params.

[ixti]

I like the idea of reference maps.

[Sannis]

+1 from me too.

[gjtorikian]

I have done this in my fork already: https://github.com/gjtorikian/panino-docs/blob/master/additionalObjs.json

I am in the process of updating Panino to the ndoc 2.0 rewrite. I can come back here and paste the relevant code changes if interested. It's just a few updates to the link() function.