How to deal with "conflicts" between qualified types in documentation?

[jvoigtlaender]

Let's say there are two modules A and B, both exporting a type T, and a third module C importing the two, and defining a function like so:

module C where
import qualfied A
import qualified B

f : A.T -> B.T

The documentation for module C will show:

f : T -> T

Little chance for readers of the documentation to find out what is going on here.

Possible solution (without resorting to always showing all qualifiers): When showing documentation for a module, collect all type names that occur in its signatures, compare them to find out which names occur in at least two different qualified forms, then always print those with qualifiers (but all other type names without qualifiers).

[mgold]

I think the proposed solution is the best that we can do, other than disallowing types of duplicate names, which would make it hard to work with Html.Attribute and Svg.Attribute.

Hmm, in another library, it would still be useful to know which Attribute you mean even if you're only using one. In the code, you'll see the import statement, but just in the docs you won't. One possibility is to require qualified types for everything not from core or the current library. Another, less restrictive solution is to get inter-module type links working.

[evancz]

I agree with the idea of showing the minimal unambiguous prefix. Most the time there's no prefix. In rare bad cases we fall back to this.

(That said, I hope no one ever designs an API like Haskell's ByteString where it's always very hard for me to figure out if I am working with a strict or lazy string.)

[mgold]

Heh, reminds me of a C library I had to work with in college, where T was typedefed to a pointer to a data structure. Confusion between &T, T, and T* ensued.

[jvoigtlaender]

In:

Hmm, in another library, it would still be useful to know which Attribute you mean even if you're only using one. In the code, you'll see the import statement, but just in the docs you won't. One possibility is to require qualified types for everything not from core or the current library. Another, less restrictive solution is to get inter-module type links working.

I think the last sentence is the important one. We should get hyperlinking of all types in docs working eventually, so should not add qualifiers where not needed.

Where we really need them is if there are otherwise conflicting names (because then the reader of the docs wouldn't even suspect that clicking the links might lead to different destinations).

Though I would amend my original proposal a bit. There, in the first comment in this issue, I said:

When showing documentation for a module, collect all type names that occur in its signatures, compare them to find out which names occur in at least two different qualified forms, then always print those with qualifiers (but all other type names without qualifiers).

I now think that instead of collecting only all type names that occur in the signatures of that module, the consideration should include all type names that occur in the signatures of the whole package the module is a part of.

So, for example, instead of looking into http://package.elm-lang.org/packages/Apanatshka/elm-signal-extra/5.2.0/docs/Signal-Discrete.json, I would be looking into http://package.elm-lang.org/packages/Apanatshka/elm-signal-extra/5.2.0/documentation.json for that.

BTW, I'm a bit perplexed about why both these files (and .../5.2.0/docs/Signal-Extra.json etc.) exist. Isn't there a lot of redundancy here? It seems that 5.2.0/documentation.json is a concatenation of all 5.2.0/docs/*.json (except that the latter contain this bug!).

Concerning implementing my proposal here: I think it's not too hard. I could try it at some point. What would help is a super easy way to extract all qualified types from a collection of the "type" strings in a file like http://package.elm-lang.org/packages/Apanatshka/elm-signal-extra/5.2.0/documentation.json. Concretely, let's say I have already extracted all its signature strings like

• "Signal.Signal (Maybe.Maybe a)"
• "(a -> a -> a) -> Signal.Stream.Stream a -> Signal.Stream.Stream a -> Signal.Stream.Stream a"
• "Signal.Stream.Stream (Maybe.Maybe a) -> Signal.Stream.Stream a"
• ...

what's the easiest way to get from this the list of strings "Signal.Signal", "Maybe.Maybe", "Signal.Stream.Stream", ...? Anybody wants to propose some magic incantation of Regex stuff?

[evancz]

I recall going through and messing with a bunch of stuff by hand with the paren bug because we couldn't track down the source. So that it's fixed only in certain places may just indicate when I did that pass. That's for another thread though.

On the regex question, all types begin with capital letters, so you could search for /\b[A-Z][a-zA-Z]*(\.[A-Z][a-zA-Z]*)*/g and find them all.

Also, I agree about the refined version. If it is ambiguous within the package then it should get a prefix. I wonder if core should be treated as "part of the package" if people are using the same names.

[mgold]

+1 for treating core types as possibly conflicting with the current module.

[jvoigtlaender]

I'm not going to give core types any special treatment. Of course, if a package defines Module.Time but also uses Time.Time, then there will be qualifiers. But this does not require any special treatment. (If something in addition is requested, then the same uncertainties come up as in inter-package-linking: Which version of core should be considered? ...)

[mgold]

The version in package.json of course. If I define a type Time as something other than Float, wouldn't you want to know that it's not the one from core?

[jvoigtlaender]

Well, I'll write the version without that additional feature. You can then extend it. 😄

[jvoigtlaender]

I've implemented what I said, in #91.

See screenshots there for the effect this has.

About Max's comments above: It's not that easy as you make it sound. What does

The version in package.json of course.

mean?

Probably you mean the elm-package.json that was uploaded for the package and version currently under display. But that file does only specify a range of possible versions for core. So one would have to go and look for the latest consistent one.

Also, it's not clear whether special casing core is really valuable. There were (still are?) considerations to split core, moving more stuff to "non-special" packages. So there would be less stuff overall which benefits from such special casing anyway.

Moreover, such special casing is outside the issue I brought up originally here, which was about displaying two types A.T and B.T as just T in package documentation. Max's point is beside that. So it should be addressed, if so, in a separate issue and pull request, after merging #91.

For the record, the basic approach for such an extension would be to, in frontend/Page/Module.elm, read the elm-package.json of an appropriate version of core, to collect all the types from there that should be "avoided" respectively disambiguated, and to merge that information into the mentionedTypes value being sent to the modulesAndMentionedTypes mailbox.

[evancz]

Yeah, it's not clear to me that this is actually plausible. Maybe the highest version in the given constraints? But I think it's the right move to just do it within the package for now.

[jvoigtlaender]

Closing this issue, since the original concern is addressed by the merging of #91.

The possible special casing concerning core discussed above remains unaddressed for now.