Add a doc to point users to kwarg builders

[fpdotmonkey]

A frequent issue that comes up with people that are first using the library is that they don't know about gdext's unique model for Gdscript's default function arguments. This gently points users to the builder functions.

Documenting every method this way is a little spammy since users only need to learn about this API once, but it's only one line, so I don't think it impacts scrolling distances much on the doc site.

[GodotRust]

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

[lilizoey]

Maybe we should also link the book? https://godot-rust.github.io/book/godot-api/functions.html?highlight=default#default-parameters
Maybe as just see also [the book](link)

[Bromeon]

Thanks, great idea! 🙂

Please also indent the attributes.

CI blocked by upstream godotengine/godot#96406.

[Bromeon]

The ?highlight=default is distracting and shouldn't be part of the link.

[fpdotmonkey]

fixed

[Bromeon]

This generates code containing a macro, which then again needs to be expanded by the compiler. Could you not create the entire doc-string at proc-macro time?

Then you could just have #[doc = #link_to_ex_function].

[Bromeon]

Any comment on this one? Why not generate the whole string at macro time and have a single #[doc] attribute? Would help readability and make it easier to change the text in the future than distributing it over 5 #[doc = ...] lines.

And who knows, maybe it helps with the rustfmt issue, too 😉

[fpdotmonkey]

Ah sorry, I should've commented. This is fixed in the version I pushed yesterday. Unfortunately, no help with the rustfmt issue.

[Bromeon]

I looked at the diff, but the current code is still

    #[doc = "To set the default parameters, use [`"]
    #[doc = #qualified_extended_fn_name_str]
    #[doc = "`] and its builder methods.  See"]
    #[doc = " [the book](https://godot-rust.github.io/book/godot-api/functions.html#default-parameters) for"]
    #[doc = " detailed usage instructions."]

So I was wondering why not a single #[doc] attribute, and do the concatenation outside, so the generated code sees only one string literal.

[fpdotmonkey]

Ah that's what you mean, ok. I'll see if I can do that this weekend.

[fpdotmonkey]

fixed

[fpdotmonkey]

Please also indent the attributes.

rustfmt won't allow that.

$ rustfmt --edition 2021 --check godot-codegen/src/generator/default_parameters.rs 
Diff in /home/fp/3rd/gdext/godot-codegen/src/generator/default_parameters.rs at line 98:
     };
 
     let functions = quote! {
-	#[doc = "To set the default parameters, use [`"]
-	#[doc = #qualified_extended_fn_name]
-	#[doc = "`] and its builder methods.  See"]
-	#[doc = " [the book](https://godot-rust.github.io/book/godot-api/functions.html#default-parameters) for"]
-	#[doc = " detailed usage instructions."]
+    #[doc = "To set the default parameters, use [`"]
+    #[doc = #qualified_extended_fn_name]
+    #[doc = "`] and its builder methods.  See"]
+    #[doc = " [the book](https://godot-rust.github.io/book/godot-api/functions.html#default-parameters) for"]
+    #[doc = " detailed usage instructions."]
         #[inline]
         #vis fn #simple_fn_name(
             #receiver_param

Possibly related to rust-lang/rustfmt#6233, but only in that it's incorrect formatting around macros.

[Bromeon]

Not sure if you've seen id, I added a comment here 🙂

[Bromeon]

Thank you! 🙂