On Mon, Nov 8, 2010 at 12:57 PM, Roman Leshchinskiy
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