CMake build scripts only generate documentation for the first XML file in `doc_classes/`

[silenuz]

Godot version

4.6.1

godot-cpp version

6388e26

System information

Linux

Issue description

This one took me a while to figure out. I was working on some documentation generation, and noticed that in one project the XML files would load and in the other they wouldn't. After about an hour checking tool chains, and whatnot, the only difference I could find between the projects was that the one that was loading the documentation did not have the example class documentation. When I remove this file in the non-working project it then works.

[dsnopek]

Just to make sure I understand correctly:

The ExampleClass is not registered in your extension, but the Summator and TrafficLight classes are. When you built your extension with the ExampleClass.xml, then all the docs failed to load. But, then when you rebuild without ExampleClass.xml, then the docs for the other classes load.

Is that correct?

If so, I wonder if the full documentation import is failing because there's a class that doesn't exist in the data. This would be a Godot bug, rather than a bug in the template.

[silenuz]

No, example class was included in register_types still.

Basically clone template, add summator and traffic light classes from your Godotcon 2024 presentation, add docs for summator and or traffic light, launch, no docs. delete ExampleClass.xml, relaunch and documentation is there. Add the example class XML file back and relaunch documentation goes away.

I can put an example in a repo if you want.

But it happens every time for me. I went through three clones of the template yesterday trying to figure out why the documentation wouldn't load till I realized that the working project did not have a ExampleClass.xml file.

Note there are nor errors or warnings from Godot, like when documentation is malformed, so my thought would be the docs are loading, just not available, but that's just a guess. And yes I'm not sure if this is template related or Godot related.

Edit:
Now I'm not sure it is loading the documentation. If I intentionally malform the documention and run the project without the ExampleClass.xml I get this error:

ERROR: Condition "parser->get_node_name() != "class"" is true. Returning: ERR_FILE_CORRUPT

However if I add ExampleClass.xml back to doc_classes then not only do I not get the the documentation, but it no longer throws the file corrupt error.

[silenuz]

This is one strange problem, but it looks like it may be engine related and not template related. I cloned the initial project I had trouble in, and changed the name of example class to ZedClass to see if the order of the xml files made a difference. I also changed the order or class registration.

After launching things are fine. I close Godot, use Godot to generate some documentation. After generating the docs, if I relaunch the documentation disappears again.

If I then delete the ZedExample.xml file and relaunch. the documentation for the Summator and TrafficLight works again. It also still happens if I don't register the ZedExample class but leave the xml file there.

[dsnopek]

If you restart the editor a few times (without deleting any files), do you sometimes get different results each time?

That's actually something I've personally seen in the past, and I think it may be related to the editor's documentation cache and timing.

Or, can it only be triggered my adding/removing the XML file, rebuilding, and restarting?

[silenuz]

Only adding / removing the xml documentation for the class in question changes anything. Once the project is built it exhibits the same behavior until it is rebuilt with / without the xml documentation for the example class.

Edit:

I was mistaken, removing the example class docs allows the next in line to be displayed, but 1 and only 1 class ever gets it's documentation added. It seems to be a problem in the godot-cpp bindings cmake scripts. I added a few messages to the configure and see that even though the template's cmake file correctly includes all the files in the doc_classes, the doc generation function in the cpp bindings (GodotCPPModulle.cmake - line 127) only ever lists one file to generate documentation for.

perhaps someone can pass this along. Building with scons works as advertised.

[dsnopek]

I was mistaken, removing the example class docs allows the next in line to be displayed, but 1 and only 1 class ever gets it's documentation added. It seems to be a problem in the godot-cpp bindings cmake scripts.

Aha, thanks for debugging!

I'm going to rename and move this issue over to the godot-cpp repo

[silenuz]

I looked into it a little more and I think it affects both projects. In CMakeLists.txt for the template there is this block of code:

# conditionally add doc data to compile output
if(DOC_XML)
    if(GODOTCPP_TARGET MATCHES "editor|template_debug")
        target_doc_sources(${LIBNAME} ${DOC_XML})
    endif()
endif()

Which calls this:

#[[ target_doc_sources
A simpler interface to add xml files as doc source to a output target.
TARGET: The gdexension library target
SOURCES: a list of xml files to use for source generation and inclusion.]]
function(target_doc_sources TARGET SOURCES)
    # set the generated file name
    set(DOC_SOURCE_FILE "${CMAKE_CURRENT_BINARY_DIR}/gen/doc_source.cpp")

    # Create the file generation target, this won't be triggered unless a target
    # that depends on DOC_SOURCE_FILE is built
    generate_doc_source( "${DOC_SOURCE_FILE}" ${SOURCES )

    # Add DOC_SOURCE_FILE as a dependency to TARGET
    target_sources(${TARGET} PRIVATE "${DOC_SOURCE_FILE}")

    # Without adding this dependency to the doc_source_generator, XCode will complain.
    add_dependencies(${TARGET} generate_doc_source)
endfunction()

Now when the template's CMakeLists.txt passes the ${DOC_XML} it is not in quotes, so doesn't this mean it will be expanded and each list item become a separate arg to the function?

Same with when the above function calls generate_doc_source, it passes the variable as is instead of in quotes, meaning generate_doc_source gets an argument for each item in the list or is this not the case?

Adding the quotes in those two places, doing a clean, and re-configuring seemed to fix it for me. For whatever reason without the clean and reconfigure after adding the quotes results in a weird message:

ERROR: Invalid tag in doc file: class.
   at: _load (editor/doc/doc_tools.cpp:1439)  

[enetheru]

yeah I thought that quoting issue was fixed, I remember a PR related to quoting not long ago.

[enetheru]

godotengine/godot-cpp#1918 was it, but i guess it wasn't fixed at that point and i forgot about it. sorry about that.

[silenuz]

Looks like there is more to it than that, as it worked for me, and then stopped working, now it always throws the invalid tag error when loaded in the editor , or when running doctool:

   at: _load (editor/doc/doc_tools.cpp:1439)

This one was my bad sorry.

This one took a while to figure out as well, if the Summator documentation XML has an invalid tag, it prevents the TrafficLight documentation from loading or maybe compiling. I kept hunting in the Trafficlight's XML file for the problem because that was the one that didn't show up, but the problem was in the Summator xml where i used <members /> for an empty members block and it did not like that.

Is this the way it's supposed to work, where an error in one class's documentation, causes the others to not load, but the one with the bad tag loads?

[enetheru]

so i wanted to submit a fix for this, but i noticed that the godot-cpp source has all the quotes. its the template project that is missing the quotes. @dsnopek can this issue be moved to the template project? I am submitting a fix for it now.

[silenuz]

I feel bad now, sorry I forgot how old my version of the bindings was. Having to move this issue back and forth and all.
Again sorry for the extra work.