Search doesn't find top-level type families

[RyanGlScott]

I've been using hoogle's search to navigate my way around the singletons library for a while, and I've noticed something odd with respect to the search results for type families. In particular, hoogle will show you associated type families, such as Demote:

$ hoogle Demote package:singletons
Data.Singletons type family Demote k = (r :: *) | r -> k

However, hoogle does not appear to show any results for "top-level" type families. For instance, it will not show the open type family Apply:

$ hoogle Apply package:singletons
No results found

Nor will it find the closed type family ShowParen, or the data family Sing. (I tried sifting through hoogle ShowParen package:singletons and hoogle Sing package:singletons, respectively, but couldn't find either one in the results.)

[ndmitchell]

This seems to be a Haddock bug - taking a look at the --hoogle output I don't see type family Apply in https://hackage.haskell.org/package/singletons-2.4.1/docs/singletons.txt - which explains why it isn't being indexed. Looking through that file I also see lots of other Haddock bugs, e.g.:

class PEq a_a1eoq => POrd (a_a1eoq :: Type) where {
    type Compare a_a1eLd a_a1eLe =
        Apply (Apply Compare_6989586621679304865Sym0 a_a1eLd) a_a1eLe;

As a line in Hoogle output should never be split.

[RyanGlScott]

Interesting, I didn't know that you could see the Hoogle documentation for any package on Hackage. A couple more questions:

1. How can I get Haddock to generate this file locally?
2. What invariants are expected to hold in these sorts of files? In other words, what makes you say that the two things you observed are bugs?

[ndmitchell]

1. Either haddock --hoogle or cabal haddock --hoogle.
2. It is expected to document everything in Haddock, so the fact something is missing is a bug. It is line-orientated, so anything with continuation lines is a bug. There was definitely some documentation on what was expected once, but I can't find it anymore... The docs remain in my head.

[RyanGlScott]

Got it, thanks. Indeed, it looks like singletons.txt is flat-out missing several things, such as in:

-- | The singleton kind-indexed data family.
type SVoid = (Sing :: Void -> Type)

In reality, that docstring should be attached to Sing, but Sing is just not there, so Hoogle mistakenly attaches the documentation to SVoid. I'll file a bug upstream in Haddock when I get a chance.

As to your second point, https://github.com/haskell/haddock/pull/432#issuecomment-129477179 suggests that the expected format for associated type families is of the form:

class Foo a where {
    type family Bar a b;
    type family Baz a;
    type Baz a = [(a, a)];
}

As an uninformed outsider, this seems to make sense to me, since I'm not sure how you'd know that Bar's parent class was Foo without this surrounding context. Does this format not work for Hoogle's purposes?

[ndmitchell]

Re the first point, thanks.

Re the second, I'm fine with the type you presented above, but:

class Foo a where {
    type family Bar a b;
    type family Baz a;
    type Baz a =
        [(a, a)];
}

Is no longer line orientated - see Compare above for a real example where it put line breaks.

[RyanGlScott]

Ah, I misunderstood what you meant by "line-orientated". That does seem like its own bug.

I think I'll file a pull request on Haddock to get this specification officially enshrined in the users' guide, given the confusion it's caused at least one person :)

[RyanGlScott]

I've opened https://github.com/haskell/haddock/issues/806 and https://github.com/haskell/haddock/issues/807 for the Haddock issues uncovered here.

Since this appears to be squarely in Haddock's territory, I'll close this issue.

[ndmitchell]

Thanks!