Hi Roman,
On Mon, Nov 8, 2010 at 2:30 PM, Roman Leshchinskiy
I would argue that documentation where every 5th word is an identifier is rather broken.
But it's not that uncommon in Haskell documentation, the main reason is probably that since the parameter names don't appear in the documentation, people refer to the arguments by type. For an example of excessive hyperlinking see: http://hackage.haskell.org/packages/archive/bytestring/0.9.1.7/doc/html/Data... "O(n) The 'intercalate' function takes a 'ByteString' and a list of 'ByteString's and concatenates the list after interspersing the first argument between each element of the list." - The documentation links to it's own definition - The documentation links to ByteString twice. In fact, the whole library links to the ByteString hundreds of times, even though people are highly unlikely to click on these links.
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.
Personally, I don't find hyperlinked identifiers to add any weight compared to monospaced ones. If anything, they are easier to read for me.
We can change the style of the @id@ markup, it's orthogonal to the hyperlinking issue. I personally like the style use in http://code.google.com/appengine/docs/python/datastore/modelclass.html where identifier are monospace but appear in a color that makes them stand out a little bit more.
I don't find their style especially enticing. In particular, they underline their hyperlinks which explains why they try to avoid them as much as possible.
Although that's not the rationale they give for not doing so. Johan