Improve GDScript documentation generation & behavior#72095
Improve GDScript documentation generation & behavior#72095YuriSizov merged 1 commit intogodotengine:masterfrom
Conversation
21b1990 to
decf8cf
Compare
4fede92 to
a6d487d
Compare
6f7dd77 to
5fb295c
Compare
|
Also, for the folks following, I updated the original post with all the things happening in this PR :) Let me know if there are any other wants that I could include here! |
712be4c to
fb759c2
Compare
YuriSizov
left a comment
There was a problem hiding this comment.
The editor side of things and the overall approach make sense to me. Needs a review from @godotengine/gdscript still.
a0d4f43 to
7c4f88b
Compare
Removes documentation generation (docgen) from the GDScript compiler to its own file. Adds support for GDScript enums and signal parameters and quite a few other assorted fixes and improvements.
| // ResourceLoader is used in order to have a script-agnostic way to load scripts. | ||
| // This forces GDScript to compile the code, which is unnecessary for docgen, but it's a good compromise right now. |
There was a problem hiding this comment.
This makes me think that perhaps the ScriptServer should be aware of documentation and just as the script language to provide documentation data. This would allow not only GDScript and other languages to optimize the doc gen process.
Of course this is just something to discuss later, no need to worry about it for this PR. I agree that loading the resource is a good compromise for now.
vnen
left a comment
There was a problem hiding this comment.
Looks good to me. Thanks for working on this!
|
This is amazing! Thanks a lot! |
|
Thanks everyone for your time, comments and support 😄 ❤️ |
|
Not sure if this is relevant, but I'd like the LSP to be integrated with docgen so we can get consistent docgen behavior. |
Rework of GDScript classes' documentation generation (docgen).
Changes:
• Removes docgen code & datastructures from⚠️ ⚠️ ⚠️ Remove unnecessary class specifier path, e.g. ⚠️ ⚠️ ⚠️ this one might be slightly contentious ⚠️ ⚠️ ⚠️
gdscript_compiler.cppandgdscript.cpp• Docgen uses analyzer datatypes instead of less expressive runtime datatypes
• Enums return/parameter types docgen'd properly instead of being
Variantorint. Fixes #71117• Makes hyperlinks to unopened classes generate their documentation on-demand rather than show blank screen.
Fixes #72406• Signals parameter types are docgen'd correctly instead of being
Variant• Added same-line docstrings for variables/constants
• Show external class specifiers e.g.
TileSet.CellNeighborinstead ofCellNeighbor,OtherClass.EnumorInnerClass.Enuminstead of justEnum•
InnerClass.Enuminstead ofCurrentClass.InnerClass.EnumorInner3.Enuminstead ofClass.Inner1.Inner2.Inner3.Enum, when documented insideInner2• Created a fairly comprehensive set of gdscript files with all/most combinations of types to make sure this works properly (linked below)
Minor changes:
• Removes unused
p_scrollparameter inEditorHelp::go_to_class()andp_vscrinEditorHelp::_goto_desc()• Removed unused
DocData::EnumDoc• Normalize docstrings in
EditorHelpsource codeEnums and class specifiers everywhere!
Before (boooooo):

After (yaaaaaay):

Inline docstrings!
Possibly contentious class specifier prefix elimination!
(see below for gdscript class & enum types)
Notice how we are within
Doc1.IC, and therefore in the highlighted areas only relevant class specifier prefixes are shown. We don't needDoc1.IC, justIC. We don't needDoc1.IC.IEorIC.IE, justIE. We don't needDoc1.IC.IICorDoc1.IC.IIC.IIE, justIICorIIC.IIE.Test files!
gdscript_docgen.zip
These are the files I used to test. They are organized as follows:
Doc1andDoc2Doc1andDoc2have an inner classIC, which has an inner inner classIIC.E,IE, andIIE.Doc1and inner classes, have methods containing all combinations of accessing classes and enums I could think of, both as parameters and return types.As far as I can tell, every type name is as I thought it made the most sense (i.e. remove prefixes which are "obvious"), and click-linking works also.