Allow options.links to inherit prototypically

[kriskowal]

With ES5 Object.create, it becomes possible for an object to be used as a dictionary (with the exception of __proto__ until ES6). It furthermore becomes possible for these to be scoped dictionaries, inheriting prototypically. This would be particularly useful as a data structure for the relevant link for a term in a particular scope.

I propose a relaxation on the "ownership" requirement on the links option. By testing instead for presence and string type, false positives from the Object.prototype are avoided for users not currently using Object.create.

[hegemonic]

My current inclination is to leave this alone until ES6 and its native Map object ride into town. I'm open to persuasion, though.

Can you provide a more concrete explanation of the benefits of this change?

Also, wouldn't this change cause problems if someone passed in, say, an instance of the following (terrible) class? This isn't an especially realistic example, but I hope that it illustrates my point:

function LinkDictionary() {}

LinkDictionary.prototype.string = 'LinkDictionary';

[kriskowal]

@hegemonic Yeah, LinkDictionary would cause a problem, but as you note, it is a bit contrived. It would also be problematic if someone were to add a string to Object.prototype as it stands today.

However! This is not necessarily the best way to achieve the goal I have in mind. It would be much better if the API were generalized to a function, like options.lookupLink(name). That way, the user could elect to use any backing store, including ES6 Map as {lookupLink: map.get.bind(map)}. The backing store I have retains lookup tables for packages, modules, and nested scopes, and is populated with information inferred from static analysis. Producing a snapshot of links in scope for each doclet is viable but expensive. I would be able to do a lot more with a function.