Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Zubin Duggal]

On 21/09/14 16:54, Simon Peyton Jones via ghc-devs wrote:


Yes, exactly. Notes have evolved into such a compellingly useful part of GHC 
that I really think they deserve Haddock support.

But here’s another tension: the Haddock for a function should be about the user 
interface; its specification.  But many Notes are specifically about the 
details of an implementation.


We could have haddock recognise and link the Note syntax in the
hyperlinked source only, not the exported documentation. Haddock could
process all comments, not just documentation comments for declarations
('-- |' '-- ^' etc.) and provide a way to identify and link to other
comments and declarations. These links could show up in the hyperlinked
source instead of the haddock page detailing the API.
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Viktor Dukhovni]

> On 14 Sep 2021, at 8:29 am, Hécate  wrote:
> 
> I may have missed an episode or two here but what prevents us from writing 
> Notes as Named Chunks¹, write them where Haddock expects you to put 
> documentation, and refer to them from the relevant spot in the code?
> Viktor (in CC) has done a wonderful work at producing nice layouts for 
> Haddocks in base, and we could learn a couple of lessons from his MRs.

Thanks for the callout.  My contribution to the documentation has thus far been
limited to just Data.Foldable and Data.Traversable, though I was hoping that
the approach might catch on if others find it a step in the right direction.

Specific content aside, in terms of haddock techniques, the main thing I
did was to append a more expansive prose overview of a library module below
the function synopses.  This did not require anything fancy, just `$section`
references from the module header.

However I also needed to occasionally create hyperlinks within the overview,
and here I ran into a limitation.  Haddock renders a hyperlink to a particular
anchor section of a module as:

Module.Name

with no syntax to customise the user-friendly text.  This means that one
is forced into some linguistic contortions to create natural sentences
with the desired hyperlinks.

This is particularly tricky when the hyperlink will appear not only in
the prose of a module's overview, but also in the synopsis of a function
or a class that may be re-exported by another module (e.g. the Prelude).

It would ideally be possible to render the hyperlink differently in its
"home" module than in a re-exporting module.

Otherwise, I found anchors and hyperlinks to be largely usable...

-- 
Viktor.

___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Ben Gamari]

Sebastian Graf  writes:

> What I don't like:
>
>- I can't refer to $chunk from other modules
>- Everywhere I reference $chunk in a haddock, it gets inlined instead of
>appearing with its title or inserting a link with the section name it is
>currently decoupled from.
>
It seems like we could easily fix both of these with a simple change to
Haddock: don't inline chunks except in references in the export list
(which determine where the chunk will be placed in the output) and
ensure that the anchor name of the chunk is predictable (e.g. based on
the chunk name). Then references from other modules (e.g. using
$MyModule.my_chunk syntax) could simply produce a link to the anchor.

Regardless, I too have long wanted to make Notes consumable from Haddock
documentation. It would be great to make progress on this.

Cheers,

- Ben



signature.asc
Description: PGP signature
___
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

RE: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Simon Peyton Jones via ghc-devs]

And as far as linking is concerned: Sure, haddocks don't have a title to refer 
to. But you can always link to them by linking to the syntactic entity! For 
example, if I want to link to DiagnosticReason from Severity, I can simply do 
so by saying "Also see 'Severity'".
I don’t like this at all!   The most important and interesting Notes are about 
the relationships between multiple distinct entities.  I don’t want to say “See 
Severity” because

  *   It’s not about Severity; it’s about the relationship between 
DiagnosticReason and Severity
  *   There might be a lot else about Severity that I want to say with 
Severity, that is nothing to do with DiagnosticReason.  I want to refer 
specifically to the note about the relationship.

Also, many, many Notes are referred to from some part of the source code of a 
function body (e.g. a guard, accompanied with “See Note [Special case for local 
ids]”).Here there is no entity to act as the anchor.  But the Note still 
might have many pointers to it.

Ideally, Haddock would simply recognise the Note syntax directly or provide a 
similar alternative

Yes, exactly. Notes have evolved into such a compellingly useful part of GHC 
that I really think they deserve Haddock support.

But here’s another tension: the Haddock for a function should be about the user 
interface; its specification.  But many Notes are specifically about the 
details of an implementation.

I have more questions than answers.   But even though Notes are incredibly low 
tech, I read and write them constantly.  I think they are a surprisingly 
powerful, albeit extremely modest, idea that GHC has given to the world.

Simon

PS: I am leaving Microsoft at the end of November 2021, at which point 
simo...@microsoft.com<mailto:simo...@microsoft.com> will cease to work.  Use 
simon.peytonjo...@gmail.com<mailto:simon.peytonjo...@gmail.com> instead.  (For 
now, it just forwards to simo...@microsoft.com.)

From: ghc-devs  On Behalf Of Sebastian Graf
Sent: 14 September 2021 15:00
To: Hécate 
Cc: ghc-devs 
Subject: Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

Hi,

I've been using Haddock's named chunks feature too when writing the docs for 
selective lambda lifting.
This is the result: 
https://hackage.haskell.org/package/ghc-8.10.2/docs/StgLiftLams.html<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhackage.haskell.org%2Fpackage%2Fghc-8.10.2%2Fdocs%2FStgLiftLams.html&data=04%7C01%7Csimonpj%40microsoft.com%7C1bd0b32d10d941aff47008d977883fda%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637672251247560036%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=sDKPBAiSSJYWjQysWkod%2BB1ewyzv4ubiwt2%2BfxEOjdI%3D&reserved=0>,
 and this is how the source code looks: 
https://hackage.haskell.org/package/ghc-8.10.2/docs/src/StgLiftLams.html<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhackage.haskell.org%2Fpackage%2Fghc-8.10.2%2Fdocs%2Fsrc%2FStgLiftLams.html&data=04%7C01%7Csimonpj%40microsoft.com%7C1bd0b32d10d941aff47008d977883fda%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637672251247570032%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=GpJji7mVYmEi3KLJeCiRFDwQRfgMXN1boZmZuynykVI%3D&reserved=0>

I quite like it. As you can see, I enabled both the existing Notes workflow and 
Haddock to work with it. It takes a bit of annoying extra work, though. 
Ideally, Haddock would simply recognise the Note syntax directly or provide a 
similar alternative.

And as far as linking is concerned: Sure, haddocks don't have a title to refer 
to. But you can always link to them by linking to the syntactic entity! For 
example, if I want to link to DiagnosticReason from Severity, I can simply do 
so by saying "Also see 'Severity'".
I do admit this might not be enough info at the reference site to determine 
whether the haddock linked to is relevant to the particular goal I want to 
achieve. Also as Simon points out, there are Notes that don't have a clear 
"owner".

Heck, even writing an unused binding `_Late_lambda_lifting_in_STG` and put the 
haddocks there would work, I suppose. We could simply link to it with 
'_Late_lambda_lifting_in_STG' from other haddocks.

My point is: If we managed to have something quite like named chunks, but with 
a title and one place it gets rendered and then linked to (I don't like that 
named chunks are inlined into every use site), we could probably agree on using 
that.
Also I'd like to see the Notes rendered *regardless* of whether the thing it is 
attached to is exported. That would make Notes a lot more accessible.

Sebastian


Am Di., 14. Sept. 2021 um 14:32 Uhr schrieb Hécate 
mailto:hec...@glitchbra.in>>:

> today’s Haddock doesn’t understand Notes.  But we could fix tha

Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Hécate]

Okay I see what you mean, thank you. :)

Le 14/09/2021 à 16:37, Sebastian Graf a écrit :

What I don't like:

  * I have to give a section name to an otherwise unused $chunk
  * I can't refer to $chunk from other modules
  * Everywhere I reference $chunk in a haddock, it gets inlined
instead of appearing with its title or inserting a link with the
section name it is currently decoupled from.


Am Di., 14. Sept. 2021 um 16:25 Uhr schrieb Hécate :

Hi,

The named chunks can be positioned through the use of the export
list syntax:

module Foo
  ( main
  -- * Section name that will appear
  --
  -- $chunk
  )

This should produce a free section that is not linked to any
exported item.
I see you're already using them though, so maybe I am
understanding something else?

Le 14/09/2021 à 16:00, Sebastian Graf a écrit :

Hi,

I've been using Haddock's named chunks feature too when writing
the docs for selective lambda lifting.
This is the result:
https://hackage.haskell.org/package/ghc-8.10.2/docs/StgLiftLams.html,
and this is how the source code looks:
https://hackage.haskell.org/package/ghc-8.10.2/docs/src/StgLiftLams.html

I quite like it. As you can see, I enabled both the existing
Notes workflow and Haddock to work with it. It takes a bit of
annoying extra work, though. Ideally, Haddock would simply
recognise the Note syntax directly or provide a similar alternative.

And as far as linking is concerned: Sure, haddocks don't have a
title to refer to. But you can always link to them by linking to
the syntactic entity! For example, if I want to link to
DiagnosticReason from Severity, I can simply do so by saying
"Also see 'Severity'".
I do admit this might not be enough info at the reference site to
determine whether the haddock linked to is relevant to the
particular goal I want to achieve. Also as Simon points out,
there are Notes that don't have a clear "owner".

Heck, even writing an unused binding
`_Late_lambda_lifting_in_STG` and put the haddocks there would
work, I suppose. We could simply link to it with
'_Late_lambda_lifting_in_STG' from other haddocks.

My point is: If we managed to have something quite like named
chunks, but with a title and one place it gets rendered and then
linked to (I don't like that named chunks are inlined into every
use site), we could probably agree on using that.
Also I'd like to see the Notes rendered *regardless* of whether
the thing it is attached to is exported. That would make Notes a
lot more accessible.

Sebastian


Am Di., 14. Sept. 2021 um 14:32 Uhr schrieb Hécate
:

> today’s Haddock doesn’t understand Notes. But we could fix
that if we were minded to.

I may have missed an episode or two here but what prevents us
from writing Notes as Named Chunks¹, write them where Haddock
expects you to put documentation, and refer to them from the
relevant spot in the code?
Viktor (in CC) has done a wonderful work at producing nice
layouts for Haddocks in base, and we could learn a couple of
lessons from his MRs.

---

Now, on the matter of improving Haddock to understand GHC's
notes, I'd like to remind everyone that Haddock is currently
understaffed in terms of feature development, and I would
like to call to everyone with experience dealing with its
codebase to give a hand in refactoring, dusting off and
improving the code so that its maintainability is not
jeopardised by people simply going elsewhere.
Our bus factor (or as I like to call it, circus factor), is
quite terrifying considering the importance of the tool in
our ecosystem.


¹

https://haskell-haddock.readthedocs.io/en/latest/markup.html#named-chunks

Le 14/09/2021 à 13:56, Simon Peyton Jones via ghc-devs a écrit :


Alfredo writes (below for full thread)

That is a deceptively simple question you ask there :-) I
don't have a strong view myself, but I can offer the
perspective of somebody who was been for a long time on the
"other side of the trenches" (i.e. working Haskell
programmer, not necessarily working GHC programmer):

* Blog post: yes, it's true that is a snapshot, and it's
true that is not under GHC's gitlab umbrella, so I wouldn't
treat it as a reliable source of documentation (for the
reasons you also explain) but it's surely a good testament
that "at this point in time, for this particular GHC commit,
things were this way);

* The wiki page: in the past, when I wanted to learn more
about some GHC feature, Google would point me to the
relevant Wiki page on the GHC repo describing such a
feature, but I

Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Sebastian Graf]

What I don't like:

   - I have to give a section name to an otherwise unused $chunk
   - I can't refer to $chunk from other modules
   - Everywhere I reference $chunk in a haddock, it gets inlined instead of
   appearing with its title or inserting a link with the section name it is
   currently decoupled from.


Am Di., 14. Sept. 2021 um 16:25 Uhr schrieb Hécate :

> Hi,
>
> The named chunks can be positioned through the use of the export list
> syntax:
>
> module Foo
>   ( main
>   -- * Section name that will appear
>   --
>   -- $chunk
>   )
>
> This should produce a free section that is not linked to any exported item.
> I see you're already using them though, so maybe I am understanding
> something else?
> Le 14/09/2021 à 16:00, Sebastian Graf a écrit :
>
> Hi,
>
> I've been using Haddock's named chunks feature too when writing the docs
> for selective lambda lifting.
> This is the result:
> https://hackage.haskell.org/package/ghc-8.10.2/docs/StgLiftLams.html, and
> this is how the source code looks:
> https://hackage.haskell.org/package/ghc-8.10.2/docs/src/StgLiftLams.html
>
> I quite like it. As you can see, I enabled both the existing Notes
> workflow and Haddock to work with it. It takes a bit of annoying extra
> work, though. Ideally, Haddock would simply recognise the Note syntax
> directly or provide a similar alternative.
>
> And as far as linking is concerned: Sure, haddocks don't have a title to
> refer to. But you can always link to them by linking to the syntactic
> entity! For example, if I want to link to DiagnosticReason from Severity, I
> can simply do so by saying "Also see 'Severity'".
> I do admit this might not be enough info at the reference site to
> determine whether the haddock linked to is relevant to the particular goal
> I want to achieve. Also as Simon points out, there are Notes that don't
> have a clear "owner".
>
> Heck, even writing an unused binding `_Late_lambda_lifting_in_STG` and put
> the haddocks there would work, I suppose. We could simply link to it with
> '_Late_lambda_lifting_in_STG' from other haddocks.
>
> My point is: If we managed to have something quite like named chunks, but
> with a title and one place it gets rendered and then linked to (I don't
> like that named chunks are inlined into every use site), we could probably
> agree on using that.
> Also I'd like to see the Notes rendered *regardless* of whether the thing
> it is attached to is exported. That would make Notes a lot more accessible.
>
> Sebastian
>
>
> Am Di., 14. Sept. 2021 um 14:32 Uhr schrieb Hécate :
>
>> > today’s Haddock doesn’t understand Notes.  But we could fix that if we
>> were minded to.
>>
>> I may have missed an episode or two here but what prevents us from
>> writing Notes as Named Chunks¹, write them where Haddock expects you to put
>> documentation, and refer to them from the relevant spot in the code?
>> Viktor (in CC) has done a wonderful work at producing nice layouts for
>> Haddocks in base, and we could learn a couple of lessons from his MRs.
>>
>> ---
>>
>> Now, on the matter of improving Haddock to understand GHC's notes, I'd
>> like to remind everyone that Haddock is currently understaffed in terms of
>> feature development, and I would like to call to everyone with experience
>> dealing with its codebase to give a hand in refactoring, dusting off and
>> improving the code so that its maintainability is not jeopardised by people
>> simply going elsewhere.
>> Our bus factor (or as I like to call it, circus factor), is quite
>> terrifying considering the importance of the tool in our ecosystem.
>>
>>
>> ¹
>> https://haskell-haddock.readthedocs.io/en/latest/markup.html#named-chunks
>>
>> Le 14/09/2021 à 13:56, Simon Peyton Jones via ghc-devs a écrit :
>>
>> Alfredo writes (below for full thread)
>>
>>
>>
>> That is a deceptively simple question you ask there :-) I don't have a
>> strong view myself, but I can offer the perspective of somebody who was
>> been for a long time on the "other side of the trenches" (i.e. working
>> Haskell programmer, not necessarily working GHC programmer):
>>
>>
>>
>> * Blog post: yes, it's true that is a snapshot, and it's true that is not
>> under GHC's gitlab umbrella, so I wouldn't treat it as a reliable source of
>> documentation (for the reasons you also explain) but it's surely a good
>> testament that "at this point in time, for this particular GHC commit,
>> things were this way);
>>
>>
>>
>> * The wiki page: in the past, when I wanted to learn more about some GHC
>> feature, Google would point me to the relevant Wiki page on the GHC repo
>> describing such a feature, but I have to say I have almost always dismissed
>> it, because everybody knows Wikis are seldomly up-to-date :) In order for a
>> Wiki page to work we would have to at least add a banner at the top that
>> states this can be trusted as a reliable source of information, and offer
>> in the main section the current, up-to-date design. We can still offer the
>> histor

Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Hécate]

Hi,

The named chunks can be positioned through the use of the export list 
syntax:


module Foo
  ( main
  -- * Section name that will appear
  --
  -- $chunk
  )

This should produce a free section that is not linked to any exported item.
I see you're already using them though, so maybe I am understanding 
something else?


Le 14/09/2021 à 16:00, Sebastian Graf a écrit :

Hi,

I've been using Haddock's named chunks feature too when writing the 
docs for selective lambda lifting.
This is the result: 
https://hackage.haskell.org/package/ghc-8.10.2/docs/StgLiftLams.html, 
and this is how the source code looks: 
https://hackage.haskell.org/package/ghc-8.10.2/docs/src/StgLiftLams.html


I quite like it. As you can see, I enabled both the existing Notes 
workflow and Haddock to work with it. It takes a bit of annoying extra 
work, though. Ideally, Haddock would simply recognise the Note syntax 
directly or provide a similar alternative.


And as far as linking is concerned: Sure, haddocks don't have a title 
to refer to. But you can always link to them by linking to the 
syntactic entity! For example, if I want to link to DiagnosticReason 
from Severity, I can simply do so by saying "Also see 'Severity'".
I do admit this might not be enough info at the reference site to 
determine whether the haddock linked to is relevant to the particular 
goal I want to achieve. Also as Simon points out, there are Notes that 
don't have a clear "owner".


Heck, even writing an unused binding `_Late_lambda_lifting_in_STG` and 
put the haddocks there would work, I suppose. We could simply link to 
it with '_Late_lambda_lifting_in_STG' from other haddocks.


My point is: If we managed to have something quite like named chunks, 
but with a title and one place it gets rendered and then linked to (I 
don't like that named chunks are inlined into every use site), we 
could probably agree on using that.
Also I'd like to see the Notes rendered *regardless* of whether the 
thing it is attached to is exported. That would make Notes a lot more 
accessible.


Sebastian


Am Di., 14. Sept. 2021 um 14:32 Uhr schrieb Hécate :

> today’s Haddock doesn’t understand Notes.  But we could fix that
if we were minded to.

I may have missed an episode or two here but what prevents us from
writing Notes as Named Chunks¹, write them where Haddock expects
you to put documentation, and refer to them from the relevant spot
in the code?
Viktor (in CC) has done a wonderful work at producing nice layouts
for Haddocks in base, and we could learn a couple of lessons from
his MRs.

---

Now, on the matter of improving Haddock to understand GHC's notes,
I'd like to remind everyone that Haddock is currently understaffed
in terms of feature development, and I would like to call to
everyone with experience dealing with its codebase to give a hand
in refactoring, dusting off and improving the code so that its
maintainability is not jeopardised by people simply going elsewhere.
Our bus factor (or as I like to call it, circus factor), is quite
terrifying considering the importance of the tool in our ecosystem.


¹
https://haskell-haddock.readthedocs.io/en/latest/markup.html#named-chunks

Le 14/09/2021 à 13:56, Simon Peyton Jones via ghc-devs a écrit :


Alfredo writes (below for full thread)

That is a deceptively simple question you ask there :-) I don't
have a strong view myself, but I can offer the perspective of
somebody who was been for a long time on the "other side of the
trenches" (i.e. working Haskell programmer, not necessarily
working GHC programmer):

* Blog post: yes, it's true that is a snapshot, and it's true
that is not under GHC's gitlab umbrella, so I wouldn't treat it
as a reliable source of documentation (for the reasons you also
explain) but it's surely a good testament that "at this point in
time, for this particular GHC commit, things were this way);

* The wiki page: in the past, when I wanted to learn more about
some GHC feature, Google would point me to the relevant Wiki page
on the GHC repo describing such a feature, but I have to say I
have almost always dismissed it, because everybody knows
Wikis are seldomly up-to-date :) In order for a Wiki page to work
we would have to at least add a banner at the top that states
this can be trusted as a reliable source of information, and
offer in the main section the current, up-to-date design. We can
still offer the historical breakdown of the designs in later
sections, as it's still valuable info to keep;

* GHC notes: I have always considered GHC notes a double-edge
sword -- from one side they are immensely useful when navigating
the source code, but these won't be rendered in the Hackage's
haddocks, and this is not helpful for GHC-the-library users
willing to understand how to use (or which is the semantic of)

Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Sebastian Graf]

Hi,

I've been using Haddock's named chunks feature too when writing the docs
for selective lambda lifting.
This is the result:
https://hackage.haskell.org/package/ghc-8.10.2/docs/StgLiftLams.html, and
this is how the source code looks:
https://hackage.haskell.org/package/ghc-8.10.2/docs/src/StgLiftLams.html

I quite like it. As you can see, I enabled both the existing Notes workflow
and Haddock to work with it. It takes a bit of annoying extra work, though.
Ideally, Haddock would simply recognise the Note syntax directly or provide
a similar alternative.

And as far as linking is concerned: Sure, haddocks don't have a title to
refer to. But you can always link to them by linking to the syntactic
entity! For example, if I want to link to DiagnosticReason from Severity, I
can simply do so by saying "Also see 'Severity'".
I do admit this might not be enough info at the reference site to determine
whether the haddock linked to is relevant to the particular goal I want to
achieve. Also as Simon points out, there are Notes that don't have a clear
"owner".

Heck, even writing an unused binding `_Late_lambda_lifting_in_STG` and put
the haddocks there would work, I suppose. We could simply link to it with
'_Late_lambda_lifting_in_STG' from other haddocks.

My point is: If we managed to have something quite like named chunks, but
with a title and one place it gets rendered and then linked to (I don't
like that named chunks are inlined into every use site), we could probably
agree on using that.
Also I'd like to see the Notes rendered *regardless* of whether the thing
it is attached to is exported. That would make Notes a lot more accessible.

Sebastian


Am Di., 14. Sept. 2021 um 14:32 Uhr schrieb Hécate :

> > today’s Haddock doesn’t understand Notes.  But we could fix that if we
> were minded to.
>
> I may have missed an episode or two here but what prevents us from writing
> Notes as Named Chunks¹, write them where Haddock expects you to put
> documentation, and refer to them from the relevant spot in the code?
> Viktor (in CC) has done a wonderful work at producing nice layouts for
> Haddocks in base, and we could learn a couple of lessons from his MRs.
>
> ---
>
> Now, on the matter of improving Haddock to understand GHC's notes, I'd
> like to remind everyone that Haddock is currently understaffed in terms of
> feature development, and I would like to call to everyone with experience
> dealing with its codebase to give a hand in refactoring, dusting off and
> improving the code so that its maintainability is not jeopardised by people
> simply going elsewhere.
> Our bus factor (or as I like to call it, circus factor), is quite
> terrifying considering the importance of the tool in our ecosystem.
>
>
> ¹
> https://haskell-haddock.readthedocs.io/en/latest/markup.html#named-chunks
>
> Le 14/09/2021 à 13:56, Simon Peyton Jones via ghc-devs a écrit :
>
> Alfredo writes (below for full thread)
>
>
>
> That is a deceptively simple question you ask there :-) I don't have a
> strong view myself, but I can offer the perspective of somebody who was
> been for a long time on the "other side of the trenches" (i.e. working
> Haskell programmer, not necessarily working GHC programmer):
>
>
>
> * Blog post: yes, it's true that is a snapshot, and it's true that is not
> under GHC's gitlab umbrella, so I wouldn't treat it as a reliable source of
> documentation (for the reasons you also explain) but it's surely a good
> testament that "at this point in time, for this particular GHC commit,
> things were this way);
>
>
>
> * The wiki page: in the past, when I wanted to learn more about some GHC
> feature, Google would point me to the relevant Wiki page on the GHC repo
> describing such a feature, but I have to say I have almost always dismissed
> it, because everybody knows Wikis are seldomly up-to-date :) In order for a
> Wiki page to work we would have to at least add a banner at the top that
> states this can be trusted as a reliable source of information, and offer
> in the main section the current, up-to-date design. We can still offer the
> historical breakdown of the designs in later sections, as it's still
> valuable info to keep;
>
>
>
> * GHC notes: I have always considered GHC notes a double-edge sword --
> from one side they are immensely useful when navigating the source code,
> but these won't be rendered in the Hackage's haddocks, and this is not
> helpful for GHC-the-library users willing to understand how to use (or
> which is the semantic of) a particular type (sure, one can click "Show
> Source" on Hackage but it's an annoying extra step to do just to hunt for
> notes). We already have Notes for this work in strategic places -- even
> better, we have proper Haddock comments for things like "Severity vs
> DiagnosticReason" , e.g.
> https://gitlab.haskell.org/ghc/ghc/-/blob/master/compiler/GHC/Types/Error.hs#L279
> 

Re: Documenting GHC: blogs, wiki pages, Notes, Haddocks, etc

[Hécate]

> today’s Haddock doesn’t understand Notes.  But we could fix that if 
we were minded to.


I may have missed an episode or two here but what prevents us from 
writing Notes as Named Chunks¹, write them where Haddock expects you to 
put documentation, and refer to them from the relevant spot in the code?
Viktor (in CC) has done a wonderful work at producing nice layouts for 
Haddocks in base, and we could learn a couple of lessons from his MRs.


---

Now, on the matter of improving Haddock to understand GHC's notes, I'd 
like to remind everyone that Haddock is currently understaffed in terms 
of feature development, and I would like to call to everyone with 
experience dealing with its codebase to give a hand in refactoring, 
dusting off and improving the code so that its maintainability is not 
jeopardised by people simply going elsewhere.
Our bus factor (or as I like to call it, circus factor), is quite 
terrifying considering the importance of the tool in our ecosystem.



¹ https://haskell-haddock.readthedocs.io/en/latest/markup.html#named-chunks

Le 14/09/2021 à 13:56, Simon Peyton Jones via ghc-devs a écrit :


Alfredo writes (below for full thread)

That is a deceptively simple question you ask there :-) I don't have a 
strong view myself, but I can offer the perspective of somebody who 
was been for a long time on the "other side of the trenches" (i.e. 
working Haskell programmer, not necessarily working GHC programmer):


* Blog post: yes, it's true that is a snapshot, and it's true that is 
not under GHC's gitlab umbrella, so I wouldn't treat it as a reliable 
source of documentation (for the reasons you also explain) but it's 
surely a good testament that "at this point in time, for this 
particular GHC commit, things were this way);


* The wiki page: in the past, when I wanted to learn more about some 
GHC feature, Google would point me to the relevant Wiki page on the 
GHC repo describing such a feature, but I have to say I have almost 
always dismissed it, because everybody knows Wikis are seldomly 
up-to-date :) In order for a Wiki page to work we would have to at 
least add a banner at the top that states this can be trusted as a 
reliable source of information, and offer in the main section the 
current, up-to-date design. We can still offer the historical 
breakdown of the designs in later sections, as it's still valuable 
info to keep;


* GHC notes: I have always considered GHC notes a double-edge sword -- 
from one side they are immensely useful when navigating the source 
code, but these won't be rendered in the Hackage's haddocks, and this 
is not helpful for GHC-the-library users willing to understand how to 
use (or which is the semantic of) a particular type (sure, one can 
click "Show Source" on Hackage but it's an annoying extra step to do 
just to hunt for notes). We already have Notes for this work in 
strategic places -- even better, we have proper Haddock comments for 
things like "Severity vs DiagnosticReason" , e.g. 
https://gitlab.haskell.org/ghc/ghc/-/blob/master/compiler/GHC/Types/Error.hs#L279 
 
.


Yes Haddock doesn’t understand Notes but that’s a deficiency in 
Haddock!  There so much in GHC that simply does not fit well with the 
Haddocks attached to a particular data decl or function.  We need 
Notes to explain how all the moving parts fit together, and to point 
to them.


Even better, we have proper Haddock comments for things like "Severity 
vs DiagnosticReason"


But I don’t think this is better – I think it is significantly 
worse!   In the case you cite, the Haddock is about DiagnosticReason, 
and mentions Severity only incidentally. I bet that the Haddock for 
Severity doesn’t refer to this. Nor is there a clear “Note [Severity 
vs DiagnosticReason]” title that bits of code across GHC can refer to 
by saying “See Note [Severity vs DiagnosticReason]”.   It’s far less 
satisfactory (to me) than a single Note that


  * covers just *one topic* (the difference between Severity and
DiagnosticReason, rather than fully describing either
  * can be *pointed to* symmetrically from both Severity and
DiagnosticReason
  * can be *pointed to* by many other bits of code

The way it is better is that today’s Haddock doesn’t understand 
Notes.  But we could fix that if we were minded to.



Returning to how to document the error-message architecture, if you’d 
prefer to use a Note than a wiki page, that’s fine.  But please write 
that Overview Note that explains all the pieces, points to them one by 
one.