Disambiguation of names

[Rufflewind]

There is a tendency in Haskell to use the same name for different things, e.g. ByteString for both the lazy and strict versions. Haddock doesn't cope with these very well, so you end up with confusing type signatures like:

fromStrict :: ByteString -> ByteString

It would be much clearer if the former were partly qualified since it originates from outside the current module:

fromStrict :: Data.ByteString.ByteString -> ByteString

The --qual flag, while it works for this case, seems to qualify nearly all the names and adding a considerable amount of verbosity to the docs. Instead, I think Haddock should only qualify names that would otherwise be ambiguous, and preferably on by default since Hackage uses only default settings.

[ggreif]

Makes a lot of sense to me. #365 describes a very similar issue.

[adamse]

Here's another example where this would be helpful: The last setEnv is actually from a different module which makes the rendered haddocks very confusing.

Maybe a heuristic like: if an entity exported from this module has the same name as the linked one use the fully qualified name?

[sjakobi]

Maybe a heuristic like: if an entity exported from this module has the same name as the linked one use the fully qualified name?

We'd also want to distinguish between different non-local identifiers of the same name, such as lazy and strict ByteString.

But, yeah, I think that's a nice idea. It could be implemented as a new --qual mode for a start.

--qual=disambiguate or -q unique maybe?

[sjakobi]

Here's another example where this would be helpful: The last setEnv is actually from a different module which makes the rendered haddocks very confusing.

BTW note that --qual=* currently wouldn't help with this case. --qual works only for identifiers in scope: https://github.com/haskell/haddock/issues/990#issuecomment-451310235

[adamse]

@sjakobi do you know where the disambiguation could take place?

Edit: it seems the backends are in haddock-api.

[sjakobi]

do you know where the disambiguation could take place?

The qualification happens here:

https://github.com/haskell/haddock/blob/39251d3aa339958aafd8b955f41323a8b0b60012/haddock-api/src/Haddock/Backends/Xhtml/Names.hs#L72

We'd want to extend this function:

https://github.com/haskell/haddock/blob/44169f4b1907e34fdf8ff84cf8b7509b1dfcaf55/haddock-api/src/Haddock/Types.hs#L566

I'm not sure where exactly to decide which identifiers need to be qualified. It's possible that Hi Haddock will make it easier though.

[philderbeast]

I have another rendered example that makes it look like Haskell has recursive type synonyms;

type TcPlugin = [CommandLineOption] -> Maybe TcPlugin.

I was like, no really when did we get recursive type synonyms? I spent about 15 mins trying to find out but then I looked at the source and saw it wasn't so.

-- GHC/Driver/Plugins.hs
type TcPlugin = [CommandLineOption] -> Maybe GHC.Tc.Types.TcPlugin

With this ambiguity in haddock rendering we could be confusing and frustrating people who are trying to get things done, people that are trying to learn the language or people digging in to see how a library works.