Pattern synonyms do not show types nor attached haddock descriptions

[ekmett]

It seems when I generate haddocks for pattern synonyms I get neither a signature for the synonym nor any attached haddock entry.

I am currently generating about 40,000 of these. It'd be really nice to be able to tell what they meant.

For bonus credit, if the pattern synonym is a simple bidirectional synonym it'd be really nice to be able to see the pattern, too.

[gergoerdi]

Showing the pattern for any pattern synonym would be like "documenting" a function by its definition. It'd tear down their defining abstraction.

[ekmett]

Alternately you can view it like seeing the definition of a constructor.

For simple enough synonyms that is all they act like.

I'd argue once you move them to class associated patterns and the more complex bidirectional patterns showing them doesn't make sense, but for the ones we can express today they are no more complex than a data constructor.

What I really care about is the associated haddock entries and types.

Right now I just get opaque walls of

GL_MAP2_TEXTURE_COORD_4
GL_MAP2_VERTEX_3
GL_MAP2_VERTEX_4
...

without even the type info to help me or my users along.

[gergoerdi]

The pattern type should definitely be in the generated docs -- if not, that's a Haddock bug for sure.

[ekmett]

and the associated -- | ... ?

[gergoerdi]

OK this is a bastard child duplicate of #333 it seems :/ With GHC 7766e5e, the following works as expected:

{-# LANGUAGE PatternSynonyms #-}
module Foo where

-- | This is a pattern synonym, like many others before it.
pattern P = ()

And the output is:

pattern P :: ()

This is a pattern synonym, like many others before it.

But note that the concrete syntax for pattern synonym signatures will have to change from that with GHC 7.10, to something like

pattern type P :: ()

Actually it might be worth switching over to that syntax in Haddock now! How do I summon a Haddock developer to do this change?

[ekmett]

It looks like I'll need to get GHC 7.8.4 or 7.10 setup just to generate
some haddocks then.

'pattern type' ?

Isn't it a term level construct? Odd name. =/

Its like how with 'ConstraintKinds' -- we only have one ConstraintKind,
which has types in it. Should have been 'ConstraintTypes' but now we're
stuck with it. =)

-Edward

On Sun, Nov 2, 2014 at 10:09 AM, Dr. Gergő Érdi notifications@github.com
wrote:

OK this is a bastard child duplicate of #333
#333 it seems :/ With GHC
7766e5e, the following works as expected:

{-# LANGUAGE PatternSynonyms #-}
module Foo where

-- | This is a pattern synonym, like many others before it.
pattern P = ()

And the output is:

pattern P :: ()

This is a pattern synonym, like many others before it.

But note that the concrete syntax for pattern synonym signatures will have
to change from that with GHC 7.10, to something like

pattern type P :: ()

Actually it might be worth switching over to that syntax in Haddock now!
How do I summon a Haddock developer to do this change?

—
Reply to this email directly or view it on GitHub
#341 (comment).

[gergoerdi]

Well type is a somewhat-relevant and handily-reserved keyword...

[ekmett]

This is one of those situations where everyone and their brother is glomming onto that keyword to make it do something different. Looking out 6 years, I am somewhat appalled by what this trend will do to our language. =(

type roles are at least about types and type families and data families are what they say on the tin, but a pattern isn't a type.

This probably isn't the forum for this discussion though.

[gergoerdi]

I am not happy about the currently-planned surface syntax either. In fact, you've just given me the final push: tomorrow I will write up the issue (pattern type is the least of it; the other is that it needs to be a type with both universial and existential type variables and two sorts of typeclass constraints!) and post it as an RFC to a wider audience.

[ekmett]

I haven't yet checked. In 7.10 do we have the richer pattern synonym types with explicit get and set syntax pairs and/or class associated pattern synonyms?

I have a bunch of things I'd like to do that would need at least the former. With the former the latter can be faked.

[gergoerdi]

Explicitly-bidirectional pattern synonyms are already in master and will be in 7.10. I haven't looked at associated pattern synonyms yet. I haven't had as much time to work on GHC, and the absolute priority for 7.10 is typechecking for pattern synonym type signatures.

[ekmett]

explicit bidirectional pattern synonyms are enough for me. thanks! lens will start (conditionally of course) exporting a bunch of them for all of its overloaded prisms when 7.10 comes out. that should rather dramatically increase adoption of pattern synonyms across the ecosystem.

[simonpj]

explicit bidirectional pattern synonyms are enough for me. thanks! lens will start (conditionally of course) exporting a bunch of them for all of its overloaded prisms when 7.10 comes out. that should rather dramatically increase adoption of pattern synonyms across the ecosystem.
That’s great!

Perhaps it would be good to have the syntactic discussion that Gergo mentioned first, though? The IDEAS are sound, I’m convinced; but it’s surprisingly hard to find a good concrete SYNTAX. We de-emphasised that when developing, but had better settle it before pattern synonyms take off.

Simon

From: Edward Kmett [mailto:notifications@github.com]
Sent: 02 November 2014 15:59
To: haskell/haddock
Subject: Re: [haddock] Pattern synonyms do not show types nor attached haddock descriptions (#341)

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/341#issuecomment-61411892.