Updating documentation

Johan Tibell 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 mailing list