Updating documentation
wren ng thornton
wren at freegeek.org
Mon Nov 8 23:16:59 EST 2010
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.
One reason this would be beneficial is that it means we wouldn't have to
stop and think about whether a given identifier has already been linked
for this page, let alone maintain the firstness quality when we decide
to rearrange the order in which things occur. Automating things like
firstness is the only reliable way to be consistent about it, just like
when giving citations in papers (e.g., many LaTeX packages will Do The
Right Thing).
Another benefit is that there is often debate about stylistic
differences like this, and so it makes sense not to hardcode that into
the documentation itself, but rather to let you change the style easily
by altering the flags you pass to haddock. When LaTeXing I do this sort
of thing often, by using semantically oriented macros whose definition
can be easily swapped out in header files according to the whims of
different journals. One of the main problems of JavaDoc, IMO, is the
focus on an operational kind of markup instead of a semantic markup that
actually captures what you mean.
Assuming I've read Ganesh Sittampalam's suggestion accurately, I'm all
for this. I may even have some time to offer once classes are out.
--
Live well,
~wren
More information about the Libraries
mailing list