Function extract_deprecated_attribute

src/parser/mod.rs:484–536

Extract `#[Deprecated]` metadata from an element's attribute lists. Supports the syntactic forms found in phpstorm-stubs: - `#[Deprecated]` — bare, no arguments. - `#[Deprecated("reason text")]` — positional reason. - `#[Deprecated(reason: "...", since: "7.2")]` — named arguments. - `#[Deprecated("reason", replacement: "...", since: "7.2")]` — mixed. Attribute names are resolved through the [`D

(
    attribute_lists: &Sequence<'_, attribute::AttributeList<'_>>,
    ctx: &DocblockCtx<'_>,
)

///
/// Returns `None` when no `#[Deprecated]` attribute is present.
pub(crate) fn extract_deprecated_attribute(
    attribute_lists: &Sequence<'_, attribute::AttributeList<'_>>,
    ctx: &DocblockCtx<'_>,
) -> Option<DeprecatedAttribute> {
    for attr_list in attribute_lists.iter() {
        for attr in attr_list.attributes.iter() {
            if !is_known_deprecated_attr(&attr.name, ctx) {
                continue;
            }

            // Bare #[Deprecated] — no argument list at all.
            let Some(arg_list) = attr.argument_list.as_ref() else {
                return Some(DeprecatedAttribute::default());
            };

            let mut reason: Option<String> = None;
            let mut since: Option<String> = None;
            let mut replacement: Option<String> = None;

            for arg in arg_list.arguments.iter() {
                match arg {
                    argument::Argument::Named(named) => {
                        let name = named.name.value.to_string();
                        let value = extract_string_literal_value(named.value, ctx.content);
                        match name.as_str() {
                            // JetBrains stubs use `reason:`, native PHP 8.4
                            // `\Deprecated` uses `message:`.  Both mean the
                            // same thing — accept either.
                            "reason" | "message" => reason = value,
                            "since" => since = value,
                            "replacement" => replacement = value,
                            _ => {}
                        }
                    }
                    argument::Argument::Positional(positional) => {
                        // First positional argument is the reason/message.
                        if reason.is_none() {
                            reason = extract_string_literal_value(positional.value, ctx.content);
                        }
                    }
                }
            }

            return Some(DeprecatedAttribute {
                reason,
                since,
                replacement,
            });
        }
    }

    None
}

/// Check whether an attribute identifier refers to one of the known
/// deprecation attributes (`\Deprecated` or `\JetBrains\PhpStorm\Deprecated`).