Skip to content

[doc] Outdated devdocs for :meta #49104

@xlxs4

Description

@xlxs4

https://github.com/JuliaLang/julia/blob/master/doc/src/devdocs/meta.md is outdated. Example:

:meta expressions are created with macros. As an example, consider the implementation of the
@inline macro:

macro inline(ex)
    esc(isa(ex, Expr) ? pushmeta!(ex, :inline) : ex)
end

Here, ex is expected to be an expression defining a function. A statement like this:

@inline function myfunction(x)
    x*(x+3)
end

gets turned into an expression like this:

quote
    function myfunction(x)
        Expr(:meta, :inline)
        x*(x+3)
    end
end

That's no longer the case, since, e.g., the inline macro was changed from

macro inline(ex)
    esc(isa(ex, Expr) ? pushmeta!(ex, :inline) : ex)
end

to

macro inline(x)
    return annotate_meta_def_or_block(x, :inline)
end

, where annotate_meta_def_or_block:

function annotate_meta_def_or_block(@nospecialize(ex), meta::Symbol)
    inner = unwrap_macrocalls(ex)
    if is_function_def(inner)
        # annotation on a definition
        return esc(pushmeta!(ex, meta))
    else
        # annotation on a block
        return Expr(:block,
                    Expr(meta, true),
                    Expr(:local, Expr(:(=), :val, esc(ex))),
                    Expr(meta, false),
                    :val)
    end
end

This change was carried out in 2a0ab37#diff-6805ce4225f84b60b14f09c34f810459b8fc107b969581982d6b3c70091b934f, as part of #41328. It essentially was done to enable @inline/@noinline annotations on function callsites.

With the new change, if the annotation is on a callsite, the generated expression is different.

In other words, while the following part of the current doc:

Here, ex is expected to be an expression defining a function. A statement like this:

@inline function myfunction(x)
    x*(x+3)
end

gets turned into an expression like this:

quote
    function myfunction(x)
        Expr(:meta, :inline)
        x*(x+3)
    end
end

holds true, if on a callsite, it should be:

function myfunction(x)
    @inline x*(x+3)
end

gets turned into an expression like this:

quote
    function myfunction(x)
        begin
            Expr(:inline, true)
            local val = x*(x+3)
            Expr(:inline, false)
            val
        end
    end
end

This is subject to minimally (?) change (?) due to #48910. I can submit a quick PR to include the new functionality in the devdocs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsThis change adds or pertains to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions