Function Attributes

[rouzwelt]

Motivation

resolves #4223
resolves #1847
resolves #4385
resolves #4377

At the moment, by default, exported Rust functions/methods generate function signature from equivalent rust types identifiers and without any documentations, unless completely handcoded using skip-jsdoc and/or typescript-custom-section, but this has some limitations as disscussed in details in issues mentioned above which have been requested to be addressed for long time, some examples of which are:

• Cannot specify documentation for each function argument or return individually unless handcoded the whole documentation block using skip-jsdoc and/or typescript-custom-section.
• Cannot return wrapped types (such as Vec<(Foo, Bar)>) as return type of async functions (and in some cases non async functions) without wrapping them in new struct and actually implementing wasm_bindgen for it.
• Cannot end up having a typed function signature in typescript (not having any in typescript) where arguments and return types are only typescript interfaces and not a js class, as JsValue in rust side where they are just serialized/deserialized using serde.
• Generated function arguments' names follow rust convention snake_case, but js/ts naming convention is camelCase, atm there is no way to convert function argument names to camelCase or optionally rename them.

Proposed Solution

By introcusing function attributes these limitations and requested features can be addressed, these attributes will make it possible to override function arguments and return types and to write specific documentation for each of them individually as desired with relatively very minimal changes:

• #[wasm_bindgen(unchecked_return_type)] and #[wasm_bindgen(return_description)] used to override function's return type and to specify description for generated js/ts bindings.
• #[wasm_bindgen(js_name)], #[wasm_bindgen(unchecked_param_type)] and #[wasm_bindgen(param_description)] applied to a rust function argument to override that argument's name and type and to specify description for generated js/ts bindings.

These attributes will provide a great level of control and customization over functions/methods generated bindings that are essential for creating well defined and structured bindings.
Let's look at some examples for more details:

/// Description for foo
#[wasm_bindgen(unchecked_return_type = "Foo", return_description = "some description for return type")]
pub async fn foo(
    #[wasm_bindgen(js_name = "firstArg", param_description = "some description for firstArg")]
    arg1: String,
    #[wasm_bindgen(js_name = "secondArg", unchecked_param_type = "Bar")]
    arg2: JsValue,
) -> Result<JsValue, JsValue> {
    // function body
}

This will generate the following js bindings:

/**
* Description for foo
* @param {string} firstArg - some description for firstArg
* @param {Bar} secondArg
* @returns {Promise<Foo>} some description for return type
*/
export function foo(firstArg, secondArg) {
    // generated body
};

And will generate the following ts bindings:

/**
* Description for foo
* @param firstArg - some description for firstArg
* @param secondArg
* @returns some description for return type
*/
export function foo(firstArg: string, secondArg: Bar): Promise<Foo>;

Same thing applies to rust struct's (and enums) impl methods and their equivalent js/ts class methods:

/// Description for Foo
#[wasm_bindgen]
pub struct Foo {
    Foo: String,
}

#[wasm_bindgen]
impl Foo {
    /// Description for foo
    #[wasm_bindgen(unchecked_return_type = "Baz", return_description = "some description for return type")]
    pub fn foo(
        &self, // cannot use function attributes on "self" argument
        #[wasm_bindgen(param_description = "some description for arg1")]
        arg1: String,
        #[wasm_bindgen(unchecked_param_type = "Bar")]
        arg2: JsValue,
    ) -> JsValue {
        // function body
    }
}

This will generate the following js bindings:

/**
* Description for Foo
*/
export class Foo {
    /**
    * Description for foo
    * @param {string} arg1 - some description for arg1
    * @param {Bar} arg2
    * @returns {Baz} some description for return type
    */
    foo(arg1, arg2) {
        // generated body
    };
}

And will generate the following ts bindings:

/**
* Description for Foo
*/
export class Foo {
    /**
    * Description for foo
    * @param arg1 - some description for arg1
    * @param arg2
    * @returns some description for return type
    */
    foo(arg1: string, arg2: Bar): Baz;
}

High Level Implementation Details

These attributes can be implemented with very minimal changes, for function arguments attributes, we need to parse and extract them before passing it token stream, and for return type attributes they will be added to attrgen! macro in crates/macro-support/src/parser.rs, this guarantees that if they were used elsewhere other than a function or a method, it'll produce error or unused code warnings.
Once they are parsed and extracted, they can be stored in the ast as follows:

/// Information about a function's return
pub struct FunctionReturnData {
    /// Specifies the type of the function's return
    pub r#type: syn::Type,
    /// Specifies the JS return type override
    pub js_type: Option<String>,
    /// Specifies the return description
    pub desc: Option<String>,
}

/// Information about a function's argument
pub struct FunctionArgumentData {
    /// Specifies the type of the function's argument
    pub pat_type: syn::PatType,
    /// Specifies the JS argument name override
    pub js_name: Option<String>,
    /// Specifies the JS function argument type override
    pub js_type: Option<String>,
    /// Specifies the argument description
    pub desc: Option<String>,
}

and then will be passed around during encode/decode process of a ast::Function to shared_api! generated Function struct which now has a new property that holds those attrs with similar format.
These new structs can be easily extended when/if more features need to be supported.
Next it'll passed as new properties of AuxExport converted from decode::Export, which makes those attrs available for consumption at crates/cli-support/js/bindings.rs where the bindings get generated.
PS: validating js_name for an arg, or validating the provided type or description dont contain any illegal chars also takes place inside added logic of crates/macro-support/parser.rs.

[daxpedda]

Please refrain from pinging maintainers like this unless there is a more specific reason then just reviewing a PR.

[daxpedda]

I believe we should not add support for optional without a good use-case. While JsValue is a good use case, we should instead discuss support for Option<JsValue> in a separate issue.

WDYT of wrapping param_type and return_type with unsafe(...), to make sure users are aware that we can't check the type here?

Thank you for doing this, great work!

[rouzwelt]

I believe we should not add support for optional without a good use-case. While JsValue is a good use case, we should instead discuss support for Option<JsValue> in a separate issue.

Makes sense, I'll remove that.

WDYT of wrapping param_type and return_type with unsafe(...), to make sure users are aware that we can't check the type here?

Yea I understand the concerns here, I personally am in the camp of the responsibility of using these attrs are upon the user/dev, as these are not something everyone needs everytime, but are something you might need at times, so using them comes with the responsibility of making sure you know what you are doing, that said, I totally understand the concerns and am totally ok to impl this or any other syntax/format you see fit for this. I can think of this format as well:
unchecked_param_type and unchecked_return_type

@daxpedda Lastly, thanks for identifying and correcting the typos and mistakes I had in documentation, and also I replied to other review comments/suggestion as well, some of which need your final call so I can go ahead to impl, so please let me know how should we go about them.

[daxpedda]

I can think of this format as well:
unchecked_param_type and unchecked_return_type

This might be more appropriate actually. Let go with that, we can do more bikeshedding after we are done.