feat: Add functionality to export doc strings on struct fields and enum variants

[timephy]

This is an "extension" of #187 and tries to also export doc strings not only on "full types" but also on the fields/variants of structs/enums.

This is also a new PR as a replacement for #228, because that PR had a "wrong commit base".

Example

#[derive(TS)]
#[ts(export_to = "tests-out/docs/")]
struct A {
    /// Doc of field
    ///
    /// Testing
    name: String,
}

is exported as (with format feature)

export type A = {
  /**
   * Doc of field
   *
   * Testing
   */
  name: string;
};

and

enum F {
    /// Doc of variant
    ///
    /// Testing
    VarA,
    /// Doc of variant
    ///
    /// Testing
    VarB(),
    /// Doc of variant
    ///
    /// Testing
    VarC {
        /// Doc of field of variant
        ///
        /// Testing
        variant_vield: i32,
    },
}

is exported as (with format feature)

export type F = "VarA" | { "VarB": never[] } | {
  "VarC": {
    /**
     * Doc of field of variant
     *
     * Testing
     */
    variant_vield: number;
  };
};

Notes

These are the "problems" that have to be thought of.

Following notes are a combination of my own observations + input from @escritorio-gustavo.

JSDocs are only shown when starting in a new line (solved)

Inserted doc strings always have a leading newline to solve this.

JSDocs are not applicable to unions (enums)

See microsoft/tsdoc#164

It seems like this is currently not possible, not even depending on the tagging-kind of enums.

[timephy]

I would like to ask for your help @escritorio-gustavo to solve these issues 🙏

• I am unsure about how or even if we should handle docs for newtypes and tuples...
• You may also please have a look how this implementation behaves when using flatten, which I did not look into yet
• I have copied the function format_docs because I needed it inside the macros module, but it is defined inside the ts-rs module, and therefore not importable..

Should we create a new utils crate?

I believe there is no way to refactor the usage of format_docs from inside ts-rs to inside macros for the doc generation for "full types", because the doc string needs to be in front of typescript's "export", which is generated from inside ts-ts... But maybe you can find a way - although we can of course just keep it this way.

[timephy]

(the commit message "exporting docs on struct fields not works" should of course be "now works", lol)

[escritorio-gustavo]

I am unsure about how or even if we should handle docs for newtypes and tuples...

Good question, I assume they currently don't export the docs right? I think we can skip documenting fields for these types as documenting the field of a newtype is kinda pointless and I'm not sure if TSDoc even renders tuple member documentation

You may also please have a look how this implementation behaves when using flatten, which I did not look into yet

Sure, I'll write some tests and push them to the PR

I have copied the function format_docs because I needed it inside the macros module, but it is defined inside the ts-rs module, and therefore not importable..
Should we create a new utils crate?

That could work, but we need to check with @NyxCode.

It's really annoying that we can't just move the function to macros and export it. Maybe we could turn format_docs into a proc_macro to do this? Seems like overkill but could also be an option

[escritorio-gustavo]

I actually think discarding is the right thing to do, documenting the field of a newtype seems pointless to me, just document the type itself

[escritorio-gustavo]

I think we can make parse_docs return the properly formatted docs as a Result<String> and eliminate format_docs entirely

[escritorio-gustavo]

I think this is now ready for merging. Thank you so much for your work on this and #187 @timephy!

[timephy]

Wonderful! Thanks for all the help! 🤝🏽