Warning duplication

[dlesbre]

Odoc duplicates warnings when a module type appears multiple times.

module type S = sig
  val foo : int -> int
  (** This raises a warning because odoc can't find Not_found
        @raises Not_found *)
end

module X : S (* warning appears a second time *)

module type S' = sig
  include S (* warning appears a third time *)
end

module Y : S' (* warning appears a fourth time *)

This clogs output. For reference on how bad it gets, I have a library with 9 @raises Not_found in the mli. This creates 188 warnings (376 lines).

[jonludlam]

Thanks for this! Yes, we can fix this.

I had a go with your library and it does indeed show many warnings. I wondered if you had tried dune build @doc-new? At least then the warnings are only for the unresolved references in your own docs, though there's still duplication due to the includes.

[jonludlam]

I should say, we can fix this within files, but not between. That is, if you have an unresolved reference in one toplevel module, and then it's included in another toplevel module, you'll see the warning twice. In most instances this won't be a huge problem though as references are only resolved at link time, and if your library is wrapped there will only be one toplevel module and hence only one call to link is required.

[dlesbre]

I had a go with your library and it does indeed show many warnings. I wondered if you had tried dune build @doc-new? At least then the warnings are only for the unresolved references in your own docs, though there's still duplication due to the includes.

I didn't know about @doc-new, however, trying it on my package doesn't seem to be an improvement... I no longer have issues with warnings for missing Stdlib reference, but I suddenly get a ton of warnings for unresolved links within my own package. These links are all correct (they generate no warning with @doc, and even when building with @doc-new, as far as I can tell, the generated docs also has all the correct links despite outputting warnings...)