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 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 same format:

struct FunctionAttributes {
    ret: FunctionComponentAttributes,
    args: Vec<FunctionComponentAttributes>,
}
struct FunctionComponentAttributes {
    ty: Option<String>,
    desc: Option<String>,
}

These new structs can be easily extended when/if more features need to be supported.
Next it'll passed as export_fn_attrs: Option<FunctionAttributes> property 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.