Comment author: @Octachron

I agree that the "constructor" class is quite misleading since it is in fact applied to any capitalized identifier, module and constructors alike. There are few places where ocamldoc could use more accurate classes (in particular for references), but in general ocamldoc does not have enough information to distinguish the two: for instance in the standard library [String] can be either the module "String" or the constructor "Arg.String".

Comment author: theindigamer

So I checked the manual and it does have a way to provide annotations (http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec333) as mentioned in section 15.2.4.2. It is just that Pervasives does not use this. It makes sense though: manually annotating all references would be very time-consuming.

If Ocamldoc were to use a deductive system to guess the type of reference that you are trying to make, that would solve the issue for the use case when there are no name conflicts. I suspect that this case happens at least as frequently as the conflicting case, if not more. So for this sub-case, the documentation author gets the benefit of correct semantics without any additional work.

Of course, this doesn't solve the problem for the "String" vs "Arg.String" case which you pointed out -- I think one has to use manual annotation in that case as in section 15.2.4.2. However, it would be very helpful if Ocamldoc emitted something like:

Warning [#warning-code] :
ambiguous cross-reference in [String]
in file 'src/foo.ml', on line 23
did you mean to use [{module:String}] or [{const:Arg.String}]?

so that the author knows that their documentation is buggy.

Comment author: @gasche

I agree that this feature sounds useful (especially with the suggested syntax that would help make the feature better-known), although deploying it in practice may be delicate if everybody's documentation warns too often.

Comment author: theindigamer

although deploying it in practice may be delicate if everybody's documentation warns too often.

Good point. I suspect that the current style.css file has the code .constructor { color : Blue } to cover this up -- modules (usually linked) and constructors look identical so the constructor colour does not make the links appear non-blue.

I think there are a couple of options:

Option 1:

If the exact look of documentation is to be kept unchanged, then make a style.css file which gives identical output but respects the new class separation. Now add the warning part in as a feature flag (say -W-ambiguous) to ocamldoc and document it on the help page, and mention this new flag under in the help information for the -css-style flag.

This way people who were using things with default settings need not be bothered. Only people using -css-style and having ambiguous naming will need to supply this additional flag (I suggest adding a warning if -css-style is supplied && there is at least one ambiguity && -W-ambiguous is not supplied).

Option 2:

If you want the default documentation to have different colours, then update style.css accordingly and making the warnings on by default, in order to avoid misleading colouring.

So option 1 means people can blissfully ignore stuff and proceed as usual, so long as they stick to the default css, which I think covers a majority of use cases. Option 2 would probably be a much ruder shock to authors of large packages.

My hunch is to go with option 1 as:

(a) a large portion of the userbase doesn't get annoyed.
(b) the portion that does get annoyed is the one using custom CSS -- they are more likely to be nitpicky about colouring than group (a), so they might not mind the warnings.

Comment author: @Octachron

@theindigamer, I fear that there may be a confusion here, the namespace indication for reference is only used to find the target of the cross-reference, it has currently no influence on the "constructor" tag. Internally ocamldoc interprets "{!namespace:Name}" as "{!namespace:[Name]}" and therefore "{!module:String}" stil generates a "constructor" span tag for "String".
However, this could be fixed.

Moreover, in absence of namespace annotation, ocamldoc already tries to find a corresponding target in all namespaces. On this point, I agree that having a warning when the name is ambiguous would be useful (even moreso since ocamldoc does not enforce any priority order beween namespaces).

Comment author: theindigamer

@Octachron, got it, I was mixing up two separate things in my head.

So to summarize, there's two uncoupled things needed to be done, right?

• Issue warnings for ambiguous names: the question is whether this should be optional or not?

• Use HTML tags based on known namespaces.

Initially, I (incorrectly) thought that the latter was an issue because we did not know the namespaces with enough resolution. So we do actually know them (apart from the ambiguous case).

Comment author: @Octachron

I believe that warnings should always be optional; at most, it could make sense to enable it by default if the specificity of the warning is high enough.

Comment author: theindigamer

Oops, I mistranslated "opt-in or opt-out" to "optional or not" from my brain to the keyboard. Warnings have to be optional, of course.

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.