Skip to content

Fix 1431#1433

Merged
jonludlam merged 3 commits into
ocaml:masterfrom
jonludlam:fix-1431
May 11, 2026
Merged

Fix 1431#1433
jonludlam merged 3 commits into
ocaml:masterfrom
jonludlam:fix-1431

Conversation

@jonludlam
Copy link
Copy Markdown
Member

@jonludlam jonludlam commented May 11, 2026

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)

Copy link
Copy Markdown
Collaborator

@panglesd panglesd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@jonludlam jonludlam added no changelog This pull request does not need a changelog entry and removed no changelog This pull request does not need a changelog entry labels May 11, 2026
@jonludlam
Copy link
Copy Markdown
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.

jonludlam added 3 commits May 11, 2026 16:10
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 jonludlam merged commit 6451247 into ocaml:master May 11, 2026
11 checks passed
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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants