Fix 1431#1433
Merged
Merged
Conversation
panglesd
approved these changes
May 11, 2026
Collaborator
panglesd
left a comment
There was a problem hiding this comment.
Even though this is not a full fix, it is at least strictly better than what we had before, in terms of behaviour.
Slight summary of the description above, since I initially misunderstood it.
We had issue #930. Then, #1400 fixed it, but introduced the other issue, #1431.
This PR restores the pre-#1400 behavior, only whenever #1431 happens. This way, we only have a problem in the "#930 + #1431 at the same time" situation, which is hopefully quite rare.
Member
Author
|
gah I was going to say this was 'no changelog' but I realised there is a need as 3.2.0 is affected by this. |
The fix for ocaml#930 introduced a problem where a local module substitution fails to resolve, which led to an unrecoverable exception being raised. This commit detects the problem and essentially leaves the signature as it was found. This means that the fix for ocaml#930 is _partial_ (and always was). The behaviour that this commit introduces is better now, but not perfect. The original ocaml#930 problem is due to a clash of identifier caused by an include with a module substitution. The fix was to turn the module substitution into a `sig ... end with module Foo :=` expression, calculate the result and use that as the body of the signature, hence no clash. This was applied universally, so any time an include had a substitution in it, we used this code. However, if the right-hand side of the module substitution was a local module, as in the test in this PR, odoc cannot resolve this, and hence raises an error. This commit detects that problem and reverts the signature to its original form. Thus the new behaviour means that there's still potential for ocaml#930, but now the condition for a problem is that there's a module substitution being included into a signature that has a module with the same name (the ocaml#930 problem), _and_ that the substitution was for a local module (the cause of ocaml#1431)
jonludlam
added a commit
to jonludlam/opam-repository
that referenced
this pull request
May 12, 2026
CHANGES: - Fix ocaml/odoc#1426, which broke docs in packages including `base` in OCaml 5.5.0 (@jonludlam, ocaml/odoc#1427) - Fix ocaml/odoc#1429, which broke docs in packages including `merlin-lib` (@jonludlam, ocaml/odoc#1430) - Fix ocaml/odoc#1431, a regression introduced in v3.2.0 (ocaml/odoc#1433, @jonludlam)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The fix for #930 introduced a problem where a local module substitution fails to resolve, which
led to an unrecoverable exception being raised. This commit detects the problem and essentially
leaves the signature as it was found. This means that the fix for #930 is partial (and
always was). The behaviour that this commit introduces is better now, but not perfect.
The original #930 problem is due to a clash of identifier caused by an include with a module
substitution. The fix was to turn the module substitution into a
sig ... end with module Foo :=expression, calculate the result and use that as the body of the signature, hence no clash.
This was applied universally, so any time an include had a substitution in it, we used this code.
However, if the right-hand side of the module substitution was a local module, as in the test in
this PR, odoc cannot resolve this, and hence raises an error. This commit detects that problem
and reverts the signature to its original form.
Thus the new behaviour means that there's still potential for #930, but now the condition for
a problem is that there's a module substitution being included into a signature that has a module
with the same name (the #930 problem), and that the substitution was for a local module (the
cause of #1431)