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