Function documentation ignored when not at toplevel

[nalimilan]

If you save the following code to a file and include() it, neither ?f nor ?g will print any documentation. Removing the if fixes the problem. This is annoying when only adding a function depending on the Julia version, notably when extending a Base function which may not exist in older releases.

if false
    """
    Do something funny.
    """
    f(x) = 1
else
    """
    Do something sad.
    """
    g(x) = 1
end

[yuyichao]

I thought this was intentional. The @doc "..." -> should still work?

[nalimilan]

Indeed it does. Maybe that's intentional and there are implications I'm not seeing, but that's certainly not user-friendly.

[tlnagy]

What was the original intent here?

[kshyatt]

@MichaelHatherly is this still a problem?

[MichaelHatherly]

Presumably covered by #20198?

[omus]

Still currently an issue. Can be seen in the wild with the LibGit2.Consts.GIT_CONFIG docstring.

[omus]

Documentation also states that docstrings in ifs should work:

if condition()
    "..."
    f(x) = x
end

[bramtayl]

Yeah I wrote those docs and I was wrong, both about if and let blocks... Sorry...

[omus]

Not a big deal. I'm not sure if this issue is going to be addressed but we should update the documentation. The working syntax is:

if true
    @doc """
    ...
    """ ->
    f(x) = x
end

[LilithHafner]

I support inserting @doc implicitly in these cases. An example in the wild is a reinterpret docstring

julia/base/reinterpretarray.jl

Lines 27 to 50 in 4ed4195

	global reinterpret
	"""
	reinterpret(T::DataType, A::AbstractArray)
	Construct a view of the array with the same binary data as the given
	array, but with `T` as element type.
	This function also works on "lazy" array whose elements are not computed until they are explicitly retrieved.
	For instance, `reinterpret` on the range `1:6` works similarly as on the dense vector `collect(1:6)`:
	```jldoctest
	julia> reinterpret(Float32, UInt32[1 2 3 4 5])
	1×5 reinterpret(Float32, ::Matrix{UInt32}):
	1.0f-45 3.0f-45 4.0f-45 6.0f-45 7.0f-45
	julia> reinterpret(Complex{Int}, 1:6)
	3-element reinterpret(Complex{$Int}, ::UnitRange{$Int}):
	1 + 2im
	3 + 4im
	5 + 6im
	```
	"""
	function reinterpret(::Type{T}, a::A) where {T,N,S,A<:AbstractArray{S, N}}

[LilithHafner]

if true
    begin
        """
        ...
        """
        f(x) = x
    end
end

works :P