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

Hécate hecate at glitchbra.in
Tue Sep 14 12:29:42 UTC 2021


 > 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 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgitlab.haskell.org%2Fghc%2Fghc%2F-%2Fblob%2Fmaster%2Fcompiler%2FGHC%2FTypes%2FError.hs%23L279&data=04%7C01%7Csimonpj%40microsoft.com%7Cdb46814133bc4404b6d308d9685a487e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637655559255320972%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=WU2dKu2Q%2FFdwntJ2h%2F6zO1Ic01c9o0VhZc5JrE0AurY%3D&reserved=0> 
> .
>
> 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.  And then copiously refer to that Note from all those places, so 
> people will update it.
>
> _Hopefully as the time goes by the new design will "spread" across all 
> the different peers working on GHC, and it will become "second nature"._
>
> I really don’t think that will happen unless there is a Note that 
> explains what the new design is!  Lacking this explicit design, 
> everyone will infer their own mental model of how it all works from 
> sundry scattered clues – and those mental models will differ.   So 
> instead of one thing “spreading”  a dozen subtly different things will 
> spread.  And then the next one, confused by these slightly different 
> clues, will be even less coherent.
>
> Let’s have one, fully-explicit version of The Plan that we constantly 
> refer to.
>
> cc’ing ghc-devs because we must constantly question and refine how we 
> describe and document GHC.
>
> Simon
>
> PS: I am leaving Microsoft at the end of November 2021, at which point 
> simonpj at microsoft.com <mailto:simonpj at microsoft.com> will cease to 
> work.  Use simon.peytonjones at gmail.com 
> <mailto:simon.peytonjones at gmail.com> instead.  (For now, it just 
> forwards to simonpj at microsoft.com.)
>
> *From:*Alfredo Di Napoli <alfredo.dinapoli at gmail.com>
> *Sent:* 26 August 2021 07:25
> *To:* Simon Peyton Jones <simonpj at microsoft.com>
> *Cc:* rae at richarde.dev
> *Subject:* Re: [Haskell Community] [Links] [Well-Typed Blog] The new 
> GHC diagnostic infrastructure
>
> Hello Simon!
>
> On Wed, 25 Aug 2021 at 13:36, Simon Peyton Jones 
> <simonpj at microsoft.com> wrote:
>
>     Alfredo
>
>     Thanks for all the work you are doing on GHC’s error message
>     infrastructure.  Your blog post gives a great overview.
>
> Thanks, and I am glad you enjoyed it :)
>
>     As you know I’m very keen for GHC to have a Note or wiki page that
>     gives a solid, up-to-date overview of all the moving parts.  (NOT
>     the design alternatives, nor the time sequence; just the
>     outcome.)  This is incredibly useful for our future selves; and it
>     helps ensure that people understand (say) the difference between
>     Severity and DiagnosticReason, and use them correctly.
>
>     So the question is: where is the canonical overview?  It could be
>
>       * Your blog post below. But that is a snapshot… you aren’t going
>         to go back to edit it as the design evolves.  And it’s not in
>         the repo.
>       * The wiki page:
>         https://gitlab.haskell.org/ghc/ghc/-/wikis/Errors-as-(structured)-values
>         <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgitlab.haskell.org%2Fghc%2Fghc%2F-%2Fwikis%2FErrors-as-(structured)-values&data=04%7C01%7Csimonpj%40microsoft.com%7Cdb46814133bc4404b6d308d9685a487e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637655559255310976%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=A%2FyWqfqPWPYUk3EpaorYP29JvLIhgcdSdcYceFIKvhc%3D&reserved=0>.
>         But it’s hard to keep up to date (it was last edited 3 months
>         ago).
>       * Note(s) in the code.  We seem to use this increasingly, and it
>         has the great merit of being part of the source code itself. 
>         But then we need clear pointer to the canonical overview
>         Notes, and need to make sure they are up to date.
>
>     I’m not advocating any particular path here… just wanting to be
>     sure that we end up with a good overview somewhere! What is your view?
>
> _TL;DR Probably a combo of a well-written (and up-to-date Wiki) plus 
> some carefully added Notes (and Haddock comments) in GHC might do the 
> trick._
>
> 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 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgitlab.haskell.org%2Fghc%2Fghc%2F-%2Fblob%2Fmaster%2Fcompiler%2FGHC%2FTypes%2FError.hs%23L279&data=04%7C01%7Csimonpj%40microsoft.com%7Cdb46814133bc4404b6d308d9685a487e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637655559255320972%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=WU2dKu2Q%2FFdwntJ2h%2F6zO1Ic01c9o0VhZc5JrE0AurY%3D&reserved=0> 
> .
>
> _So, in practical terms, I suggest we (I) give the Wiki a little 
> overhaul to add at the top the current design (or anything not 
> captured directly in GHC's source code) and I will keep an eye on the 
> GHC notes and Haddock comments to see if there is anything worth 
> adding. Hopefully as the time goes by the new design will "spread" 
> across all the different peers working on GHC, and it will become 
> "second nature"._
>
> Hope it helps, and sorry for the long ramble!
>
> Alfredo
>
>     Thanks
>
>     Simon
>
>     *From:*Alfredo Di Napoli via Haskell Community
>     <discourse at haskell.org>
>     *Sent:* 23 August 2021 11:26
>     *To:* Simon Peyton Jones <simonpj at microsoft.com>
>     *Subject:* [Haskell Community] [Links] [Well-Typed Blog] The new
>     GHC diagnostic infrastructure
>
>     Image removed by sender.
>
>     	
>
>     *adinapoli*
>     <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdiscourse.haskell.org%2Fu%2Fadinapoli&data=04%7C01%7Csimonpj%40microsoft.com%7Cdb46814133bc4404b6d308d9685a487e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637655559255330973%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=PgX4crGMBTWVwI2UMcq%2BIFDZ0dDr%2FRWNYZdV%2Fqi8mX8%3D&reserved=0>
>
>     August 23
>
>     Image removed by sender.*well-typed.com*
>     <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwell-typed.com%2Fblog%2F2021%2F08%2Fthe-new-ghc-diagnostic-infrastructure%2F&data=04%7C01%7Csimonpj%40microsoft.com%7Cdb46814133bc4404b6d308d9685a487e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637655559255340965%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=X51rdrGoKmUBPB8upLVL69LyInf%2BsYYQqM%2Fd4PnLnGQ%3D&reserved=0>
>
>
>     *Error! Filename not specified.*
>
>
>           The new GHC diagnostic infrastructure - Well-Typed: The
>           Haskell Consultants
>           <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwell-typed.com%2Fblog%2F2021%2F08%2Fthe-new-ghc-diagnostic-infrastructure%2F&data=04%7C01%7Csimonpj%40microsoft.com%7Cdb46814133bc4404b6d308d9685a487e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637655559255340965%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=X51rdrGoKmUBPB8upLVL69LyInf%2BsYYQqM%2Fd4PnLnGQ%3D&reserved=0>
>
>     ------------------------------------------------------------------------
>
>     *Visit Topic*
>     <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdiscourse.haskell.org%2Ft%2Fwell-typed-blog-the-new-ghc-diagnostic-infrastructure%2F2918%2F1&data=04%7C01%7Csimonpj%40microsoft.com%7Cdb46814133bc4404b6d308d9685a487e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637655559255350960%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=tOfAGO5BbhanwBDgMA6eqpgKCLcLTtkum8QOuMsROdc%3D&reserved=0>
>     or reply to this email to respond.
>
>     You are receiving this because you enabled mailing list mode.
>
>     To unsubscribe from these emails, *click here*
>     <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdiscourse.haskell.org%2Femail%2Funsubscribe%2F962dfad7651b2ce3d7e30ba9267bdb857c77298d6fdec12626b65e014aaeee33&data=04%7C01%7Csimonpj%40microsoft.com%7Cdb46814133bc4404b6d308d9685a487e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637655559255360954%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=4616hEpSSUcOZ5zQYZMmEbF6mTJcIVKx2nlgA8ENsHM%3D&reserved=0>.
>
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

-- 
Hécate ✨
🐦: @TechnoEmpress
IRC: Hecate
WWW:https://glitchbra.in
RUN: BSD
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20210914/02c9daf8/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.jpg
Type: image/jpeg
Size: 823 bytes
Desc: not available
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20210914/02c9daf8/attachment.jpg>


More information about the ghc-devs mailing list