Describe the project you are working on:
Creating plugins for Godot.

Describe the problem or limitation you are having in your project:

Let's say I define an addon with a collection of script classes. If someone else installs my addon, they have no way to easily determine what the intended use/API is for those scripts. I can't state what the purpose of my script is for, which methods are public versus protected/private, which methods are static, which methods are virtual (and intended to be overridden). I can't specify in which cases a method or class should be used, how constants and signals relate to the API, etc.

The only way for someone to glean any of this information is to go to the script itself and read the source code which is antithetical to the purpose of building an addon for others to use. They shouldn't need to know the details of how the addon works; they only need to know what they can use the addon for and how to use it.

We should provide a mechanism by which people can generate in-editor documentation for script classes and be able to rebuild this documentation on command / via a recurring process / something-or-other.

Describe how this feature / enhancement will help you overcome this problem or limitation:

And God said, "Let there be script documentation," and there was script documentation.

Integrating user-defined script documentation would be the most direct, clean, and efficient means of solving the problem. The editor already has built-in support for this with engine types. There is just no code at the moment that actively searches for and integrates user-defined documentation data and rebuilds the in-editor docs cache as scripts change, nor is there anything that generates that information.

Show a mock up screenshots/video or a flow diagram explaining how your proposal will work:

Add a button to rebuild documentation manually in the ScriptEditor.

The information above would all be filled in with our own custom script class's name, properties, methods, etc.

Since private/public data concepts are not built into GDScript and Godot's scripting except through naming conventions, we could set things so that only items without leading underscores appear in the documentation.

Once, later on, the scripting API supports recognizing annotations for scripts in general, and GDScript gets annotation support, then we can start to directly mark things as private/public, virtual, etc.

Would one day like to be able to do something like this:

extends Node
class_name MyNode

# Despite method having a leading underscore, this specially marks that
# the method should be exposed to API documentation.
@public
@desc Summary about how this does a thing.
    More information on it doing that thing.
    This is injected straight into the XML, i.e. you can use Godot's XML doc features:
    Now I'm referencing a Godot class: [Node].
    Default implementation can be found in [method MyNode._override_me].
    Here's an example of how you should override it...
    [codeblock]
    extends MyNode
    @override # indented @-signs don't impact outer annotation
    func _override_me() -> int:
        return 1
    [/codeblock]
@virtual
func _override_me() -> int:
    return 0

But none of the docs stuff is 100% dependent on the annotations. It just helps fill in information. A lot of the boilerplate functionality can be achieved without annotations thanks to the inclusion of scripting API reflection information (godotengine/godot#31021)

Describe implementation detail for your proposal (in code), if possible:

1. Cache an original copy of the engine's DocData information.
2. Write a method in the Editor's DocData or other docs-related, centralized API, to fetch a collection of XML files from all existing addons directories (res://addons/*/docs/*.xml for example) or sub-projects (whenever godotengine/godot#19178 is implemented). It would then build the content of those files into a DocData instance and merge it into the editor's cached DocData instance in order to update and replace the main DocData instance. The main one will then automatically cause Godot's ScriptEditor GUI to update with the correct script information.
3. Write a method to generate boilerplate XML files from one or more scripts.
   • If annotation support is in the engine (Annotations in GDScript godot#20318), then use that information to help fill out the content inside the XML data.
4. Whenever script classes are regenerated, we would also want to regenerate XML docs in a background thread.

If this enhancement will not be used often, can it be worked around with a few lines of script?:

It would be used extremely often. The entire addon script ecosystem is hamstrung by the lack of this feature. We need an integrated solution. It would be a decently large amount of script work to build the tools necessary to do all of this.

Is there a reason why this should be core and not an add-on in the asset library?:

Honestly, with the exception of the annotation stuff (cherry-on-top material) and the DocData merging/searching code (which isn't exposed to scripts yet), a lot of this can be done from the scripting API with an EditorPlugin now that script reflection info is exposed to scripts. But even if we fixed the basic problems of exposing the right stuff, a user shouldn't need to install a plugin that then enables them to generate documentation on how to use a plugin. That would be ridiculous.

Other Related Issues:

• Allow class_name to also add a description godot#23047
• Add to In-Engine Scripting API Documentation with a Plugin godot#10635