> 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
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:*Alfredo Di Napoli <alfredo.dinap...@gmail.com>
*Sent:* 26 August 2021 07:25
*To:* Simon Peyton Jones <simo...@microsoft.com>
*Cc:* r...@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
<simo...@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
<discou...@haskell.org>
*Sent:* 23 August 2021 11:26
*To:* Simon Peyton Jones <simo...@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@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
--
Hécate ✨
🐦: @TechnoEmpress
IRC: Hecate
WWW:https://glitchbra.in
RUN: BSD
_______________________________________________
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
