try to add doc comments to functions

[0x53A]

I'm attempting to add more documentation to the API and opened the PR relatively early to gather feedback.

---

Currently, there is no documentation on the autogenerated functions from the godot API:

Example:

https://godot-rust.github.io/docs/gdext/master/godot/classes/struct.Camera2D.html

This PR adds some boilerplate text, and a link to the godot online docs:

---

At minimum I'll need to properly detect properties by reading the field from the json (https://raw.githubusercontent.com/godot-rust/godot4-prebuilt/refs/heads/4.4/res/extension_api.json), in the rust code it's currently commented out:

gdext/godot-codegen/src/models/json.rs

Line 63 in 20cd346

// pub members: Option<Vec<Member>>,

This is relevant for link generation, and I'm trying to auto-detect it by the get_ / set_ prefixes, but there are godot methods with a get_ prefix, for example Camera2D.get_limit, which now falsely get detected as a property.

---

Additionally it would be great to verbatim include the documentation, and this is available in XML format here.

[GodotRust]

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

[0x53A]

Well, I noticed something weird:

the 4 properties limit_bottom, limit_left, limit_right, limit_top all refer to the same two methods: set_limit and get_limit.

(https://docs.godotengine.org/en/stable/classes/class_camera2d.html#class-camera2d-property-limit-left)

		<method name="set_limit">
			<return type="void" />
			<param index="0" name="margin" type="int" enum="Side" />
			<param index="1" name="limit" type="int" />
			<description>
				Sets the camera limit for the specified [enum Side]. See also [member limit_bottom], [member limit_top], [member limit_left], and [member limit_right].
			</description>
		</method>
	</methods>
	<members>
		<member name="limit_bottom" type="int" setter="set_limit" getter="get_limit" default="10000000">
			Bottom scroll limit in pixels. The camera stops moving when reaching this value, but [member offset] can push the view past the limit.
		</member>
		<member name="limit_left" type="int" setter="set_limit" getter="get_limit" default="-10000000">
			Left scroll limit in pixels. The camera stops moving when reaching this value, but [member offset] can push the view past the limit.
		</member>
		<member name="limit_right" type="int" setter="set_limit" getter="get_limit" default="10000000">
			Right scroll limit in pixels. The camera stops moving when reaching this value, but [member offset] can push the view past the limit.
		</member>
		<member name="limit_top" type="int" setter="set_limit" getter="get_limit" default="-10000000">
			Top scroll limit in pixels. The camera stops moving when reaching this value, but [member offset] can push the view past the limit.
		</member>

In the C++ implementation, they do pass the SIDE as the last parameter of the macro:

https://github.com/godotengine/godot/blob/46c495ca21f40f57a7fb9c7cde6143738f1652d4/scene/2d/camera_2d.cpp#L964-L967

	ADD_PROPERTYI(PropertyInfo(Variant::INT, "limit_left", PROPERTY_HINT_NONE, "suffix:px"), "set_limit", "get_limit", SIDE_LEFT);
	ADD_PROPERTYI(PropertyInfo(Variant::INT, "limit_top", PROPERTY_HINT_NONE, "suffix:px"), "set_limit", "get_limit", SIDE_TOP);
	ADD_PROPERTYI(PropertyInfo(Variant::INT, "limit_right", PROPERTY_HINT_NONE, "suffix:px"), "set_limit", "get_limit", SIDE_RIGHT);
	ADD_PROPERTYI(PropertyInfo(Variant::INT, "limit_bottom", PROPERTY_HINT_NONE, "suffix:px"), "set_limit", "get_limit", SIDE_BOTTOM);

So at least in some cases I'd need to keep the documentation for the function, even if it is part of a property.

[Bromeon]

Thanks for the contribution!

---

This PR adds some boilerplate text, and a link to the godot online docs:

To be honest I don't think the boilerplate is very useful. This reminds me of the "Javadoc best practice" 🙂

/**
 * Get the position.
 *
 * Returns the position of the object as a 2D vector.
 *
 * @return position of the object.
 */
Vector2 getPosition();

If we change docs, we should rather go the full mile and import the real docs from Godot. See also #584 (this extends to classes and utilitiy functions, not just builtin types).

This would also obviate the need for per-method links, and messing with properties. We still have the class link on the top of each page.

---

Additionally it would be great to verbatim include the documentation, and this is available in XML format here.

It's even better, this is now available in the JSON, when invoking Godot with --dump-extension-api-with-docs instead of --dump-extension-api. I'm not sure if this contains all the information necessary though, and it would require an update to the prebuilt library.

We could maybe start supporting it in api-custom as a first step.

[0x53A]

To be honest I don't think the boilerplate is very useful.

I agree! Depending on how complex ingesting the actual docs is, I would still see some value in relatively quickly adding the link to the online docs though.