Documenting `@concrete` structs

[ParadaCarleton]

"""
    Object

Parameters:

- `x`: Stores information.
"""
@concrete terse struct Object
    x
end

This throws an error:

'@concrete' not documentable. See 'Base.@__doc__' docs for details.

[jonniedie]

Thanks for the issue. I’ll check out why this isn’t working.

[jonniedie]

Hm. It seems that it only has a problem when the terse keyword is used. I'm actually not too sure how to debug this one at the moment. This is another good reason to start thinking about implementing #5.

[mrazomej]

+1 on this request. Being able to document all @concrete structs would be fantastic.

[Ickaser]

A simple workaround is:

@concrete terse struct Object
    x
end

@doc """
    Object

Parameters:

- `x`: Stores information.
"""
Object

[tpapp]

Currently, it gives an informative error:

using ConcreteStructs

"Docs"
@concrete terse struct Beton
    cement
end

results in

ERROR: LoadError: cannot document the following expression:

begin
    #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:84 =#
    struct Beton{__T_cement} <: Any
        #= /tmp/tmp.jl:5 =#
        cement::__T_cement
        function Beton(cement::__T_cement) where __T_cement
            #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:142 =#
            #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:143 =#
            return new{__T_cement}(cement)
        end
    end
    #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:85 =#
    function Base.show(io::IO, T::Type{<:Beton})
        #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:85 =#
        #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:86 =#
        if T isa UnionAll
            #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:87 =#
            print(io, "Beton")
        else
            #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:89 =#
            print(io, "Beton" * "{" * join(T.parameters[1:0], ",") * "}")
        end
    end
    #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:92 =#
    function Base.show(io::IO, ::Base.Multimedia.MIME{Symbol("text/plain")}, T::Type{<:Beton})
        #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:92 =#
        #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:93 =#
        if T isa UnionAll
            #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:94 =#
            return print(io, "Beton")
        else
            #= /home/tamas/.julia/packages/ConcreteStructs/7Lv7u/src/ConcreteStructs.jl:96 =#
            return print(io, "Beton" * "{" * join(T.parameters, ",") * "}")
        end
    end
end

which makes sense.

Suggested API workaround: if @concrete is followed by a string, it is taken to be the docstring for the struct, as in

@concrete "Docs" terse struct Beton
    cement
end

If people think this makes sense I could make a PR.

[tpapp]

Or, alternatively, the macro could put the Base.show methods inside the struct ... end.

[AntonOresten]

Note that the latest release (0.2.3) fails only on terse, but terse works fine on main as this was fixed in #9:

(@v1.12) pkg> add https://github.com/SciML/ConcreteStructs.jl
    Updating git-repo `https://github.com/SciML/ConcreteStructs.jl`
   Resolving package versions...
     Project No packages added to or removed from `~/.julia/environments/v1.12/Project.toml`
    Manifest No packages added to or removed from `~/.julia/environments/v1.12/Manifest.toml`

julia> using ConcreteStructs

julia> "test"
       @concrete terse struct PlainTerseDoc end

help?> PlainTerseDoc
search: PlainTerseDoc PlainTerseDoc1

  test

so I think we just need a new release. Project.toml on main is way ahead, at v0.2.5.

[tpapp]

Thanks. Is there anything blocking the release? This would be useful.

[ChrisRackauckas]

it needed a url fix in general, just got it done.

[ChrisRackauckas]

Release was 3 days ago JuliaRegistries/General#155574

[tpapp]

Now I am very confused, @AntonOresten says it is fixed on 0.2.5, but main is at 0.2.4. But 0.2.4 tests already have this test case so is it fixed in 0.2.4?

[ChrisRackauckas]

0.2.4 is the latest source code and main.

[AntonOresten]

Main was previously ahead of the registry (0.2.3) by two patch versions (0.2.5). Chris un-bumped it in f9d5789 to (0.2.4) to match what the next release would actually be.

@ChrisRackauckas it seems TagBot isn't executing properly still, with the latest tag being 0.2.2, which makes things even more confusing😆

[ChrisRackauckas]

Yes just enabled it, when its cron job hits it'll do all of the missing ones.