Base.@doc in macro doesn't work on master

[Tortar]

As the title says this seems to be the case because in a PR on SumTypes.jl (https://github.com/MasonProtter/SumTypes.jl/pull/63/files) the doctest failing is only on nightly, while all the other works well, as you can see at https://github.com/MasonProtter/SumTypes.jl/actions/runs/7595253256/job/20687608559 the test fails with

Basics  : Test Failed at /home/runner/work/SumTypes.jl/SumTypes.jl/test/runtests.jl:40
  Expression: string(#= /home/runner/work/SumTypes.jl/SumTypes.jl/test/runtests.jl:40 =# @doc(Foo)) == "This is a Foo.\n"
   Evaluated: "nothing" == "This is a Foo.\n"

while for all other Julia versions it returns "This is a Foo.\n". Same is happening also on the CI of ProtoStructs.jl e.g. here https://github.com/BeastyBlacksmith/ProtoStructs.jl/actions/runs/7500520539/job/20419369109

Unfortunately I wasn't able to find a MWE when I searched for it

[vtjnash]

This is a REPL-only feature. Packages should normally be using @ref links, not copying the text from elsewhere. E.g.:

$ ./julia -E '@doc Base'
nothing
$ ./julia -E 'using REPL; @doc Base'
```
Base
```

The base library of Julia. `Base` is a module that contains basic functionality (the contents of `base/`). All modules implicitly contain `using Base`, since this is needed in the vast majority of cases.

[KristofferC]

This doesn't make sense to me... Why would the docsystem work differently if the REPL is loaded? Seems something should be moved back to Base.

[jmert]

See also #52141.

[JamesWrigley]

This also hit the Clang.jl tests. Here's a MWE:

doc_expr = (@macroexpand @doc throw)
docstring = string(@doc throw)

@show Base.hasdoc(Main, :throw)
@show doc_expr
@show docstring

And the output on v1.11 alpha

$ julia +1.11 --startup-file=no mwe.jl
Base.hasdoc(Main, :throw) = true
doc_expr = nothing
docstring = "nothing"

Vs 1.10.2 (without Base.hasdoc()):

$ julia --startup-file=no mwe.jl
doc_expr = :((Base.Docs.doc)((Base.Docs.Binding)(Main, :throw)))
docstring = "```\nthrow(e)\n```\n\nThrow an object as an exception.\n\nSee also: [`rethrow`](@ref), [`error`](@ref).\n"

It looks like the macro is returning a nothing value instead of an Expr?

[KristofferC]

One issue with this is that @doc gives you are markdown object, which is defined in another stdlib.

[JeffBezanson]

I think we should have @doc x return the un-rendered doc object, so it can still be used to duplicate doc strings without the REPL being loaded. It doesn't really matter what @doc x does in the REPL since most people use ? to look up docs anyway.

[ztangent]

Noticed this a while back as well! See JuliaLang/Pkg.jl#3650.

[ztangent]

Could I ask what the intended return value of @doc x is before the REPL module is loaded, and whether it should be equal to the value of @doc x after REPL is loaded? After testing out the nightly, I'm seeing that different values get returned. Here's a MWE:

using Test

"my function"
function foo()
    return 0
end

io = IOBuffer()
print(io, @doc foo)
docstr1 = String(take!(io))

using REPL

io = IOBuffer()
print(io, @doc foo)
docstr2 = String(take!(io))

println("docstr1 = ")
println(docstr1)

println("docstr2 = ")
println(docstr2)

@test docstr1 == docstr2

The resulting output is below:

docstr1 =
Base.Docs.DocStr(svec("my function"), nothing, Dict{Symbol, Any}(:typesig => Tuple{}, :module => Main, :linenumber => 3, :binding => foo, :path => "C:\\Users\\...\\test.jl"))
docstr2 =
my function

Test Failed at C:\Users\...\test.jl:24
  Expression: docstr1 == docstr2
   Evaluated: "Base.Docs.DocStr(svec(\"my function\"), nothing, Dict{Symbol, Any}(:typesig => Tuple{}, :module => Main, :linenumber => 3, :binding => foo, :path => \"C:\\\\Users\\\\...\\\\test.jl\"))" == "my function\n"

As a result, docstring tests like the one in Gen.jl#3 are still failing, and will behave differently depending on whether the test suite is run in the REPL vs. during CI (when REPL isn't loaded).

[KristofferC]

Having the return type change like this just because REPL is loaded or not doesn't seem great. Couldn't @doc always return the raw string form?

[lgoettgens]

Having the return type change like this just because REPL is loaded or not doesn't seem great. Couldn't @doc always return the raw string form?

I agree and thus created #54664 to discuss further.