21. Attributes and documentation metadata

21.1 Declaration attributes

CS-METADATA-001. Declaration metadata follows the declaration header and precedes its members/executable body. Attributes support compact and block forms. Their constructor/named-argument semantics are ordinary CLR attribute semantics; target legality is validated from metadata. Attribute suffix omission is accepted where unambiguous.

public class CustomerExport
    attributes Global.System.SerializableAttribute()

    public CustomerId as Global.System.Guid
    public DisplayName as String
        attributes Global.System.Text.Json.Serialization.JsonPropertyNameAttribute("display_name")
end class

The equivalent metadata placement in C# is [Serializable] before the class and [JsonPropertyName("display_name")] before the property. Source placement differs; CLR metadata does not.

CS-METADATA-002. Parameter metadata follows the complete parameter declaration, including its default, using with attributes. Return metadata follows its type with the same phrase. Parameter/return attribute blocks are not supported.

public action PrintLabel(
    name as String with attributes Global.System.Diagnostics.CodeAnalysis.DisallowNullAttribute()
)
    Global.System.Console.WriteLine(name)
end action

C#-style bracket shorthand is allowed on parameters for interoperability. It does not extend to classes, actions, constructors, properties or fields. Assembly-level attributes belong to the project declaration.

Attributes are metadata for the target platform/library. They do not replace core concepts such as needs, readonly bindings or service lifetimes.

21.2 Structured descriptions

CS-METADATA-003. description is structured documentation metadata owned by a meaningful declaration, not a runtime attribute. It can document classes, data, interfaces, kinds, enums/members, actions, constructors, appropriate properties/fields, parameters and results. Ordinary locals and transient statements use comments instead.

public action FormatCustomerLabel(
    id as Global.System.Guid description "Stable customer identifier.",
    name as String description "Customer display name."
)
    returns String description "A printable label containing both values."
    description "Formats a customer label for reports and support tools."

    return "{{name}} ({{id}})"
end action

CS-METADATA-004. /// remains available for richer free-form documentation. Tooling may emit descriptions as normal XML summary, param and returns documentation and display them in IntelliSense. Magic comment prefixes are not an alternative structured channel.

Reject metadata on an illegal CLR target, unresolvable/ambiguous attribute types, invalid constructor arguments, parameter/return attribute blocks and description attached to an ordinary local.

Specification contents · Previous: 20. Dependency injection and services · Next: 22. Extensions