Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Type of @doc x changes when REPL is loaded #54664

Open
lgoettgens opened this issue Jun 4, 2024 · 6 comments
Open

Type of @doc x changes when REPL is loaded #54664

lgoettgens opened this issue Jun 4, 2024 · 6 comments
Labels
bug Indicates an unexpected problem or unintended behavior docsystem The documentation building system

Comments

@lgoettgens
Copy link
Contributor

#54499 approached to fix #52986 (to no longer return nothing without REPL).
But as @ztangent and @KristofferC discussed in #52986 (comment), the returned object is still different, making tests like probcomp/Gen.jl#523 and Nemocas/AbstractAlgebra.jl#1716 fail.

IMO, an okay solution would be to add some repr (or similar) method for Base.Doc.DocStr, so that at least string(@doc x) is consistent between 1.10 and 1.11+.

@lgoettgens
Copy link
Contributor Author

Bump. I still see it as quite a drastic change between 1.10 and 1.11 @KristofferC @JeffBezanson

jmert added a commit to jmert/BitFlags.jl that referenced this issue Jun 19, 2024
The change in JuliaLang/julia#54499 fixed the ability to access/copy
doc strings without needing to take an explicit dependency on the
REPL package, but the returned object does not trivially reduce back
to a string, as described in issue JuliaLang/julia#54664.

Instead of waiting for that issue to get resolved at the Julia level
to fix our tests, just add a helper shim to the tests to access the
desired information. The goal is to just ensure that the macro
`@__doc__` expression is correctly used to permit documenting the
generated type definitions, so we don't really care about the specific
form as long as Julia uses it correctly within the docs system.
jmert added a commit to jmert/BitFlags.jl that referenced this issue Jun 19, 2024
The change in JuliaLang/julia#54499 fixed the ability to access/copy
doc strings without needing to take an explicit dependency on the
REPL package, but the returned object does not trivially reduce back
to a string, as described in issue JuliaLang/julia#54664.

Instead of waiting for that issue to get resolved at the Julia level
to fix our tests, just add a helper shim to the tests to access the
desired information. The goal is to just ensure that the macro
`@__doc__` expression is correctly used to permit documenting the
generated type definitions, so we don't really care about the specific
form as long as Julia uses it correctly within the docs system.
jmert added a commit to jmert/BitFlags.jl that referenced this issue Jun 19, 2024
The change in JuliaLang/julia#54499 fixed the ability to access/copy
doc strings without needing to take an explicit dependency on the
REPL package, but the returned object does not trivially reduce back
to a string, as described in issue JuliaLang/julia#54664.

Instead of waiting for that issue to get resolved at the Julia level
to fix our tests, just add a helper shim to the tests to access the
desired information. The goal is to just ensure that the macro
`@__doc__` expression is correctly used to permit documenting the
generated type definitions, so we don't really care about the specific
form as long as Julia uses it correctly within the docs system.
@stevengj stevengj added the docsystem The documentation building system label Aug 9, 2024
@stevengj
Copy link
Member

stevengj commented Aug 9, 2024

Note that, according to git bisect, the return type of @doc first broke in 30ccace (#51869).

@KristofferC
Copy link
Member

I was confused about that commit because all it does is to load a package so it shouldn't do anything but alas JuliaLang/StyledStrings.jl#61

@lgoettgens
Copy link
Contributor Author

Bump

@lgoettgens
Copy link
Contributor Author

I think we discussed @doc always returning a String which the REPL then parses into Markdown to display.
(@KristofferC in #52986 (comment))

@LilithHafner LilithHafner added the bug Indicates an unexpected problem or unintended behavior label Sep 26, 2024
@aplavin
Copy link
Contributor

aplavin commented Oct 8, 2024

This regression appears to be still present in the 1.11 release: @doc returns an internal Base.Doc.DocStr object when called from tests.
Breaks the tests, with no straightforward way to have the same tests succeed on both 1.10 and 1.11.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Indicates an unexpected problem or unintended behavior docsystem The documentation building system
Projects
None yet
Development

No branches or pull requests

5 participants