wren ng thornton wrote:
On 11/8/10 5:41 AM, Johan Tibell wrote:
On Mon, Nov 8, 2010 at 12:36 PM, Sittampalam, Ganesh wrote:
That feels to me like a rule that would be better applied by the documentation tool, than by the individual writing the documentation. Especially as the syntax is more lightweight than in Java, it's so much easier to just automatically do it for everything than to stop and think each time.
In my experience, I don't think there's automatic way to decided where to link or not. It's really a judgement call (and I sometimes go back and remove or add hyperlinks). Sometimes I don't hyperlink an identifier even the first time it's mentioned, for example because it was hyperlinked in the introduction.
I believe the suggestion was not to add hyperlinks automatically, but rather to *remove* them automatically. For example, with such automation I can just write 'Int', 'Foo', or 'Local.Bar' everywhere and leave it up to Haddock to ensure properties like only the first one actually being a link.
That was my suggestion, and I think Johan's objection is that it's not possible to get the same results, because the inclusion or otherwise of hyperlinks is also subject to a judgement call. His suggested overall criterion is that links should only be used when the user is likely to want to click on them, and he gives the (more mechanical) rules as suggestions that might help documenters make that judgement. Personally I think the gap in quality that can be achieved by using human judgement rather than the mechanical rules is small, and in fact users might rather have consistency. The other advantages you list also weigh in favour of the automation. Cheers, Ganesh =============================================================================== Please access the attached hyperlink for an important electronic communications disclaimer: http://www.credit-suisse.com/legal/en/disclaimer_email_ib.html ===============================================================================