lsegal/yard — pull request #647 by amireh (2013-02-02 14:34:23+00:00)
Title: Custom reference links support

The feature allows the registration of arbitrary "link keywords" that
can be used to link against certain object types. This is handy when
defining custom CodeObject implementations where referencing them by
path is unnatural and not human readable.

Modifications:
* RegistryStore now tracks object_links which is a keyword ->
object_type map
* Proxy objects can now act as "links" and resolve themselves
* HTMLHelper#link_object handles linkable Proxy objects

There are specs that cover the added methods, and all
the modifications are documented with proper YARD syntax.

For lack of better place to write an example, here's what the feature would allow a user to do:

```ruby
# @see Spec: name of spec
# @see Appendix: YARD Pipeline
```
As opposed to:

```ruby
# @see .spec.path_to_spec Spec: name of spec
# @see .appendix.namespace.appendix_name Appendix: YARD Pipeline
```

Or whatever the object paths might be.

---

I tried to find the proper place to write some example of how to use the feature outside the actual API documentation (there's a proper example in the Registry.register_link method) but I wasn't sure. So if you're good with the changes and would like to merge them, I'll be happy to write the end-user doc for it.

*PS: we talked about this on IRC last night, my alias is kandie.*