Document arguments for the freestanding attribute [SE-0397]

[tadbyt]

Location

https://docs.swift.org/swift-book/documentation/the-swift-programming-language/attributes#freestanding

Description

The freestanding attribute description is incomplete. It doesn't define any of its arguments.

Correction

The arguments to this attribute indicate the macro’s role and provide requisite supplemental information.

The first argument to this attribute indicates the macro’s role:

Expression macros

Write expression as the first argument to this attribute. The type that implements the macro conforms to the ExpressionMacro protocol. These macros create a piece of code that returns a value. For example, a calculation that doesn’t merit a function.

Declaration macros

Write declaration as the first argument to this attribute. The type that implements the macro conforms to the DeclarationMacro protocol. These macros create one or more declarations. For example, generating data structures from a template or other data format (e.g., JSON).

Unlike attached macros, a freestanding macro must have precisely one role.

A declaration macro can expand to any declaration that is syntactically and semantically well-formed within the context where the macro is expanded, with a few notable exceptions:

• import declarations
• a type with the @main attribute
• extension declarations
• operator and precedencegroup declarations
• macro declarations
• top-level default literal type overrides

When a declaration macro declaration includes the names: argument, the macro implementation must generate only symbols with names that match that list. That said, a macro need not generate a symbol for every listed name. The value for that argument is a list of one or more of the following:

• named(<#name#>) where name is that fixed symbol name, for a name that’s known in advance.
• arbitrary for a name that can’t be determined until macro expansion. This may not be used at the top-level.

rdar://116543744