Generate valid XML from doc comments

[andreymal]

Closes #837

Escapes everything (things like Gd<Node> in function parameters must also be escaped)

Removes the empty line before the XML declaration to make XML valid

if matches!(...) in xml_escape looks ugly but makes it ~20% faster no longer relevant, see the old commit if you're curious

[andreymal]

(I have no idea how to run godot::tests::docs::correct)

[GodotRust]

API docs are being generated and will be shortly available at: https://godot-rust.github.io/docs/gdext/pr-861

[Bromeon]

Thanks a lot, very nice amendment!

godot::tests::docs::correct

Should be run as part of ./check.sh test, no?

[andreymal]

Should be run as part of ./check.sh test, no?

No ¯\(°_o)/¯

[Bromeon]

Ah, it needs the register-docs feature.

[andreymal]

xml_escape is now optimized for the case when most strings don't contain special characters.

Since this caused the list of special characters to be present three times, I decided to remove matches!(...) for the sake of simplicity. While it may still improve performance a bit, it's not that important now

[Bromeon]

Thanks! It looks like unit-tests in CI may not have the register-docs feature enabled, so I'm not sure if the things are actually tested? If not, that's something I should fix before merging...

[MrJoermungandr]

Yo I've found that currently the Variable Documentation isnt working so if i do

struct Test {
base: Base<Resource>,
/// # Awesome Doc
/// Immaculate Documentation
#[export]
var: Type
}

it doesnt show in the Inspector. Dont know if thats a seperate issue since its clearly experimaental :)

[andreymal]

in the Inspector

@MrJoermungandr you need to #[export] variables to the inspector, see the book https://godot-rust.github.io/book/register/properties.html#exporting-variables

(and don't forget to enable the register-docs feature)

(and this is off-topic here btw)

[MrJoermungandr]

Sry i exported it ofc and also have the feature enabled ^^ i only meant that it says No Description Available mb.
When i extend it in GdScript it works fine.
I can open another Issue tho if thats not the scope of this pr just thought i'll report here first :)

EDIT: Actually masasive brainfart on my side since i didnt actually test with this pr only with the previous functionality im sorry for bothering will check again if this is merged ^^ 🥴

[andreymal]

This pull request reveals another issue: if .godot/extension_list.cfg doesn't exist, the documentation shows Rust types instead of Godot types (which is quite expected, this is literally what's written in XML)

Doesn't seem to be related to this pull request, it just helped to reveal this issue

[Bromeon]

Thanks a lot!

We can gladly add further improvements in other PRs, but this is already a nice improvement that deserves merging on its own 🙂

Edit: I'll need to make sure the CI actually runs the unit-test with the register-docs feature. Will do that today.

[Bromeon]

Tried to integrate register-docs into tests but couldn't get it to work in the short time I had. Will do another time...