Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ts2Fable should generate empty param xml elements for parameters that are missing typescript comments #417

Open
baronfel opened this issue Jul 27, 2021 · 2 comments

Comments

@baronfel
Copy link

Reecent F# compilers warn on missing param names in XML Documentation, so generated xmldocs should be exhaustive here to prevent confusion.

Here's a sample from generated vscode APIs:

    module Authentication =

        type [<AllowNullLiteral>] IExports =
            /// <summary>Register an authentication provider.
            /// 
            /// There can only be one provider per id and an error is being thrown when an id
            /// has already been used by another provider. Ids are case-sensitive.</summary>
            /// <param name="id">The unique identifier of the provider.</param>
            /// <param name="label">The human-readable name of the provider.</param>
            /// <param name="provider">The authentication provider provider.</param>
            abstract registerAuthenticationProvider: id: string * label: string * provider: AuthenticationProvider * ?options: AuthenticationProviderOptions -> Disposable

note the missing options parameter here, which causes FS3390 to be fired.

@Booksbaum
Copy link
Contributor

Sometimes it's even worse: not only are params missing -- but use a non-existing name:

For example:
https://github.com/microsoft/vscode/blob/ffb40deb5251a524da79cbfbdb0e16af6b658802/src/vs/vscode.d.ts#L7340-L7347
(oldUri -> source; newUri -> target)
(though it seems to at least keep the order -> might be recoverable)

Note:
Since #414 ts2fable emits a #nowarn "3390" when there are xml comments (-> disable warnings about XML comments). That was easier than fixing all xml doc issues.
(Additional to invalid or missing params, quite often transformed links (<see cref=... in F#) turn out to be invalid (point to something TypesScripty or to something external. Also there a ton of different styles for links in JS with some resulting in incorrect translations))

@baronfel
Copy link
Author

baronfel commented Aug 3, 2021

yeah I noticed the names as well (though truly those are bugs on the vscode side of things).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants