johan.tibell at gmail.com
Mon Nov 8 06:56:54 EST 2010
On Mon, Nov 8, 2010 at 12:57 PM, Roman Leshchinskiy <rl at cse.unsw.edu.au> wrote:
> Why? I always try to hyperlink identifiers.
Hyperlinking something draws the users attention. Hyperlinking
everything is almost the same as making e.g. every 5th word bold.
> This provides some syntax highlighting in the comments which I find very useful. Besides, making the reader search for the first occurence of an identifier doesn't sound like a good idea to me. Documentation is rarely read linearly.
You can use @id@ to make the identifier monospaced. It makes it clear
that's it's an identifier without the visual weight of a link.
By first occurrence I mean first occurrence in some context. Perhaps
the context is the documentation of a function. Use your judgement.
You're right that documentation is often not read linearly. That
applies to Javadoc as well and it's there they established this
More information about the Libraries