It seems like just about everything is working, except for global variable names for autoloads. As stated above:

# deprecated_autoload.gd
extends Node

## This autoload is registered with the name DeprecatedAutoload,
## and is marked as deprecated.
## @deprecated

func do_thing():
   print("a thing has been done")

# main.gd
func _ready():
    # DeprecatedAutoload will *not* show as deprecated
    DeprecatedAu...

I've spent a fair amount of time this evening trying to figure out how to get to the DocData::ClassDoc for an autoload, and based on the existing code it looks like I'd need some kind of function that maps script paths to ClassNodes (or DocData::ClassDocs).

What are others' thoughts about not displaying global variable names for autoloads as deprecated even if they're marked as deprecated in their GDScript file's documentation comments?

From what I see autoload doc data is also registered in EditorHelp::get_doc_data().class_list under the name of the autoload, but the update behavior seems very flaky so I'm not sure whether we can rely on it.

Besides that the only way I know of would be getting the path of the autoload, loading the script and getting the info from the script.

Would need some testing regarding performance impact though, since in the worst case autocompletion gets called with every keystroke so we need to make sure that the resource loader caches the script and doc.

In general before merging we need to test this PR for performance. We already have the problem, that autocompletion can trigger parsing and analyzing of a lot of scripts with each keystroke. This PR shouldn't add more scripts to that list.

From what I see autoload doc data is also registered in EditorHelp::get_doc_data().class_list under the name of the autoload, but the update behavior seems very flaky so I'm not sure whether we can rely on it.

I'm finding this to be shaky as well. I have a test project that I'm using, and can do the following:

1. I delete the project's .godot folder, then open the project. If I go straight to "Search Help" and start typing the name of the global variable the autoload is registered under, it appears in the list.
2. I make a change to a script file in the project and save it, then close the project.
3. I re-open the project and go to "Search Help" again, and start typing the name of the global variable the autoload is registered under. It doesn't appear anymore.

Indeed, using the following snippet:

for (const KeyValue<String, DocData::ClassDoc> &E2 : EditorHelp::get_doc_data()->class_list) {
    print_line(vformat("Class %s found", E2.key));
}

I do get the following output:

...
Class PackedColorArray found
Class PackedVector4Array found
Class @GlobalScope found
Class @GDScript found
Class DeprecatedAutoload found
Class DeprecatedClass found
Class MyScene.InnerDeprecatedClass found
Class MyScene found

(where DeprecatedAutoload is the name of the autoload's global variable, not its class_name).

And indeed, if I delete .godot then open the project, I can get the DeprecatedAutoload to display as deprecated:

So it seems to me like something being cached in .godot is causing the doc generation to halt prematurely, such that autoloads aren't being added. Last night as I was working on this, I noticed my other custom classes also weren't printing out. I'll look into getting an issue filed for this, if one doesn't already exist!

Regarding performance, I agree that's definitely a big concern, and one I've been conscious of as I've been working through putting this feature together. Across the file, there are a few ways I've gotten deprecated data from the docs:

When I have the Node for a symbol, I can grab the data from it directly via something like member.m_class->doc_data.is_deprecated. As far as I can tell, this would have very little overhead.

For checking if a class is deprecated, I have to get EditorHelp::get_doc_data()->class_list and access it by key. This seems like it might have a bit more overhead.

So far, I'm most nervous about when I want to check whether signals/properties/methods on some class are deprecated. My process so far has been to:

1. Get the ClassDoc for the given class.
2. Create an empty HashMap<StringName, bool> to store names and whether or not they are deprecated.
3. Iterate over the relevant vector within the ClassDoc, and for each item, add an entry to the HashMap where the key is the item's name and the value is whether or not the item is deprecated.
4. When creating the vector of CodeCompletionOptions, check if each one exists in the HashMap, and if so, set its deprecated value to the corresponding value in the HashMap.

In practice, that looks like this:

// Up at the top of the method, so it can be reused:
const HashMap<String, DocData::ClassDoc> class_doc_map = EditorHelp::get_doc_data()->class_list;

// ...

// Here we're going to create the list of constants to provide as autocomplete suggestions.
HashMap<StringName, Variant> constants;
scr->get_constants(&constants);

// Create a HashMap mapping constants' names to their deprecated status.
HashMap<StringName, bool> const_is_deprecated_map;
for (const DocData::ConstantDoc &constant_doc : class_doc_map.get(base_type.class_type->get_global_name()).constants) {
    const_is_deprecated_map.insert(constant_doc.name, constant_doc.is_deprecated);
}

for (const KeyValue<StringName, Variant> &E : constants) {
    int location = p_recursion_depth + _get_constant_location(scr, E.key);
    ScriptLanguage::CodeCompletionOption option(E.key.operator String(), ScriptLanguage::CODE_COMPLETION_KIND_CONSTANT, location);

    // Add the constant's deprecated status if we have it.
    if (const_is_deprecated_map.has(E.key.operator String())) {
        option.deprecated = const_is_deprecated_map.get(E.key.operator String());
    }
    r_result.insert(option.display, option);
}

Without changing how the doc data is structured, I'm not sure how this could be made much more efficient. These hashmaps could perhaps be computed earlier on, alongside the rest of the doc data, and then cached? Although then that introduces multiple sources of truth for deprecated statuses, which isn't ideal.

For checking if a class is deprecated, I have to get EditorHelp::get_doc_data()->class_list and access it by key. This seems like it might have a bit more overhead.

I wouldn't worry about hashmap lookups and such, that should be fine. Just triggering parsing and analyzing for a script can get very expensive.

There was an issue where I was attempting to access editor theming, and causing some of the CI to fail, but I think I found a fix for that. If all the checks don't pass, I'll try to continue working through them on another branch so that they put less strain on the main repo's CI resources 😅

Just a note that after #91060 local variables and constants can also be deprecated/experimental. Not sure how useful this is in practice and whether LSP supports deprecating local identifiers, but it would be nice to add it.

For me, practically speaking, it doesn't make sense for a local variable to be deprecated - if so then I feel like it's time for a refactor of your code 😅 But, if documentation comments are parsed for local identifiers and that includes deprecated status, I also agree that for consistency's sake it should be added.

And added it is! I may not push it to the branch that this PR is tracking immediately, as I'd like to get the CI issues resolved first.

I'm currently working on getting the CI checks to pass. By adding the deprecated argument to CodeEdit::add_code_completion_option, I broke compatibility for that method and am now trying to get a compatibility method for it to work correctly. To avoid using Godot's CI resources but still run the checks, I'm continuing it on the branch at https://github.com/Meorge/godot/tree/language-server-tomfoolery-dev. It seems to be failing with the "Hash changed" error.

In code_edit.compat.inc:

void CodeEdit::_add_code_completion_option_compat_100019(CodeCompletionKind p_type, const String &p_display_text, const String &p_insert_text, const Color &p_text_color, const Ref<Resource> &p_icon, const Variant &p_value, int p_location) {
	add_code_completion_option(p_type, p_display_text, p_insert_text, p_text_color, p_icon, p_value, p_location, false);
}

void CodeEdit::_bind_compatibility_methods() {
	// ...
	ClassDB::bind_compatibility_method(D_METHOD("add_code_completion_option", "type", "display_text", "insert_text", "text_color", "icon", "value", "location"), &CodeEdit::_add_code_completion_option_compat_100019, DEFVAL(Color(1, 1, 1)), DEFVAL(Ref<Resource>()), DEFVAL(Variant::NIL), DEFVAL(LOCATION_OTHER), DEFVAL(false));
}

In code_edit.h:

#ifndef DISABLE_DEPRECATED
	// ...
	void _add_code_completion_option_compat_100019(CodeCompletionKind p_type, const String &p_display_text, const String &p_insert_text, const Color &p_text_color = Color(1, 1, 1), const Ref<Resource> &p_icon = Ref<Resource>(), const Variant &p_value = Variant::NIL, int p_location = LOCATION_OTHER);
	static void _bind_compatibility_methods();
#endif

And, in 4.3-stable.expected:

GH-100019
--------
Validate extension JSON: Error: Field 'classes/CodeEdit/methods/add_code_completion_option/arguments': size changed value in new API, from 7 to 8.

New argument `deprecated` added to `add_code_completion_option`. Compatibility method registered.

However I'm still getting the error:

Compatibility to 4.3-stable is broken in the following ways:
Validate extension JSON: Error: Hash changed for 'classes/CodeEdit/methods/add_code_completion_option', from EB1A746E to 611C3D20. This means that the function has changed and no compatibility function was provided.

I feel like I've followed all of the steps at https://docs.godotengine.org/en/stable/contributing/development/handling_compatibility_breakages.html, so I'm feeling a bit out of ideas at the moment... 😅

At the GDScript meeting today, this PR was discussed and it was proposed to see how this functionality could potentially be merged with #101370 .

If that PR provides a more uniform, reliable interface to symbol documentation, then I think that approach could be better than what I do in this PR. I'll have to try pulling the other PR and prototyping out the deprecated symbol support in the coming days.

Looking through #101370 some more, I feel like I understand a bit better how these two PRs would fit together. I don't think the other PR would change much about how this PR would function.

The general flow, as I understand it, is:

• The code structure is analyzed for potential completion candidates. This is where this PR adds the information about whether or not something is deprecated.
• If the user is typing arguments for a function, then Editor: Use documentation tooltip for function autocompletion #101370 uses the information from the previous step to look up and display the relevant documentation.

Because this PR performs its actions before #101370, merging the latter first wouldn't change how this one would work. However, the deprecation status data added to completion options by this PR might be able to be incorporated into #101370 to display whether or not the function a user is currently trying to use is deprecated.

Probably not my place to ask, but what's the rationale behind using ## @deprecated comments rather than a @deprecated before a symbol's declaration like with @rpc, @export, etc.? I think most people would figure it's more consistent than a comment thing.

They are an already-existing feature in documentation comments; this PR simply reads the data from that.

Somewhere along the line, it looks like the Godot script editor support for deprecated symbols in the autocomplete was broken, so now they don't appear with the strikethrough anymore. However, they still appear correctly in VS Code. I'll be able to look more into this soon.

Strikethrough issue should be fixed! On macOS, the line does feel like it might be ever-so-slightly higher than it should be, but I'm not sure how it appears on other platforms, or how "incorrect" this actually is:

Could you amend the commit message to remove the noise caused by previous intermediate commits being squashed?

There are 4 pages worth of this:

I noticed most of your merged PRs ended up having similar noise in the git log, which can't be corrected now, but it would be good that current and future PRs have a cleaner commit message (see https://github.com/godotengine/godot/blob/master/CONTRIBUTING.md#format-your-commit-messages-with-readability-in-mind ).

When rebasing, you can use fixup instead of squash to squash commits while discarding the message of the fixup commit(s).

Certainly, will work on doing that now! Sorry for the long concatenated messages on the previous ones; I'll ensure I keep those short and clean for future PRs as well 😅