Function check_needs_update

src/code_actions/update_docblock.rs:569–723

Check whether the docblock needs updating.

(
    info: &FunctionWithDocblock,
    content: &str,
    local_classes: &[Arc<ClassInfo>],
    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
    function_loader: FunctionLoader<'_>,
    use_

/// Check whether the docblock needs updating.
fn check_needs_update(
    info: &FunctionWithDocblock,
    content: &str,
    local_classes: &[Arc<ClassInfo>],
    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
    function_loader: FunctionLoader<'_>,
    use_map: &HashMap<String, String>,
    file_namespace: &Option<String>,
) -> bool {
    // Build a map of existing doc param names.
    let doc_param_names: Vec<&str> = info
        .doc_params
        .iter()
        .map(|p| {
            let n = p.name.as_str();
            n.strip_prefix("...").unwrap_or(n)
        })
        .collect();

    let sig_param_names: Vec<String> = info.sig_params.iter().map(|p| p.name.clone()).collect();

    // When the docblock already has at least one @param tag the user has
    // opted-in to documenting parameters, so every signature param is
    // relevant.  When the docblock has *zero* @param tags we only consider
    // params that need enrichment (matching generate-docblock behaviour).
    let has_any_doc_params = !doc_param_names.is_empty();

    if has_any_doc_params {
        // Check for missing, extra, or reordered params.
        if doc_param_names.len() != sig_param_names.len() {
            return true;
        }
        for (doc_name, sig_name) in doc_param_names.iter().zip(sig_param_names.iter()) {
            if *doc_name != sig_name.as_str() {
                return true;
            }
        }
    } else {
        // No @param tags at all — only flag if a param needs enrichment.
        let needs_enrichment = info
            .sig_params
            .iter()
            .any(|sp| enrichment_plain(sp.type_hint.as_ref(), class_loader).is_some());
        if needs_enrichment {
            return true;
        }
    }

    // Check for type contradictions in @param tags.
    for sig_param in &info.sig_params {
        if let Some(native_type) = &sig_param.type_hint
            && let Some(doc_param) = info.doc_params.iter().find(|dp| {
                let n = dp.name.as_str();
                let n = n.strip_prefix("...").unwrap_or(n);
                n == sig_param.name
            })
            && is_type_contradiction(&doc_param.type_parsed, native_type)
        {