jsdoc3/jsdoc — pull request #271 by mathematicalcoffee (2012-11-26 23:51:50+00:00)
Title: Improve link tag, jsdoc3/jsdoc#250

See jsdoc3/jsdoc#250.

### Following changes made to the `{@link}` tag:

* support link text for symbols `{@link Foo.Bar|my class}`, `{@link Foo.Bar my class}` (it is already supported for URLs)
* support both spaces and pipes as link text delimeters. (Use the pipe if present; otherwise use the first space).
* tests added for various delimiter cases, both symbols and URLs

**NOTE, possible regression**: one of the tests had to be disabled. `{@link test."long blah"/blah}` used to turn into `test."long blah"/blah` because the test did a `helper.registerLink('test."long blah"/blah', 'path/to/...')`.

Because of the space in this, it would be interpreted as a link to symbol `'test."long` with caption `blah"/blah`. Since that symbol doesn't exist, just the content is shown (so `{@link test."long blah"/blah}` gets turned into `blah"/blah`).

For now I've changed the test from `it` to `xit`, but should I instead modify the behaviour of a link that appears to have both link and content, but the link is dead?

For example, should `{@link Foo|Bar}` be translated into `Foo|Bar` or `Bar` if `Foo` does not exist (for now it is the latter)?

### Configurations added:

* `conv.templates.monospaceLinks`, false by default: if true, all `{@link }` will be rendered in monospace.
* `conf.templates.cleverLinks`, false by default: if true, all `{@link}` will be rendered in monospace if it is a link to a symbol, and in normal font otherwise. This overrides the value of `monospaceLinks`.
* tests added with various combinations of `monospaceLinks` and `cleverLinks` to make sure they work and that `cleverLinks: true` overrides any value of `monospaceLinks`.

### Tags added:

* `{@linkplain}`: things in here are rendered with no explicit font, regardless of `monospaceLinks` or `cleverLinks`.
* `{@linkcode}`: things in here are rendered in monospace font, regardless of `monospaceLinks` or `cleverLinks`.
* tests added for the above (also checking that they are respected with various `monospaceLinks` and `cleverLinks` settings).

### todo
* if this pull request is accepted, I need to learn how to update the docs.