Simplified syntax for @link tag

[GoogleCodeExporter]

This is an enhancement suggestion (but I couldn't find a way to tag it as
such).

The syntax for the @link tag has been copied directly from javadoc, which
in my opinion is unfortunate. I think we (and they) can do better. Here are
a number of suggestions

1. @link Printer other text  -- Uses first whitespace to terminate link
2. @link "Longer Link" text  -- Accepts " to keep the linked word
3. @link{Link,linked text}   -- Generic tag argument format

Using the {@link Link linked text} syntax seems backwards to me, since the
parenthesis are always added after the name in most languages. Also, no
separator between the arguments is used, so we cannot extend this to 3
arguments easily.

The #3 syntax above is the one I would recommend, since it should be
possible to generalize to all tags. E.g. @param{arg,the argument}.
Alternative #1 and #2 might be poor choices due to parsing complexity, but
would be more logical for users. They wouldn't work for the enhancement
suggestion with generic link text though.

Thanks for all the great work on jsdoc!

Original issue reported on code.google.com by cederb...@gmail.com on 12 Jan 2009 at 8:38

[GoogleCodeExporter]

I don't think the designers of the JavaDoc syntax were thinking of @link as a 
function, as you are, but rather 
as a template token, as in PHP: "Go to the {$link} to learn more."

In that case the {@link} syntax looks very much at home. However there is 
already a ticket for a syntax like 
this: {@link name [text]} which was posted by me!

see: issue #174

I don't mind extending the @link syntax with some backwards-compatible options, 
but radically changing the 
syntax would mean that I would have to maintain and document both syntaxes, and 
in my opinion the value 
gained does not warrant the extra work.

Original comment by micmath on 26 Jan 2009 at 9:29

• Changed state: WontFix