Updating documentation

[Johan Tibell]

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
guideline.

Johan