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

Better documetation of Overloading types #2002

Closed
adamjosefus opened this issue Jul 13, 2022 · 2 comments
Closed

Better documetation of Overloading types #2002

adamjosefus opened this issue Jul 13, 2022 · 2 comments
Labels
enhancement Improved functionality plugin idea This feature may be best suited for a plugin

Comments

@adamjosefus
Copy link

Problem

If you are using overloading type in your functions/methods, the builder documentation is not really helpful in this task.

Code Example A:

type Entry =
    | [title: string, content: string, button: string]
    | [title: string, content: string, button: string, options: Options]
    | [title: string, content: string, primary: string, secondary: string, options: Options];

function myFunction(...entry: Entry): void {
    // Some code...
}

VS Code intellisense:
Snímek obrazovky 2022-07-13 v 19 53 52
Snímek obrazovky 2022-07-13 v 19 53 52

Code Example B:

function myFunction(param1: string): void;
function myFunction(param1: number, param2: boolean): void;

function myFunction(param1: string | number, param2?: boolean): void {
    // Some code...
}

VS Code intellisense:
Snímek obrazovky 2022-07-13 v 19 50 14
Snímek obrazovky 2022-07-13 v 19 50 22

Suggested Solution

  • Detect type for overloading and include it next to the function.
  • Render all argument possibilities
@adamjosefus adamjosefus added the enhancement Improved functionality label Jul 13, 2022
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Jul 17, 2022

This is going to be a tricky one I think... should be possible, but by no means trivial.

@Gerrit0 Gerrit0 added the help wanted Contributions are especially encouraged label Jul 17, 2022
@Gerrit0 Gerrit0 added plugin idea This feature may be best suited for a plugin and removed help wanted Contributions are especially encouraged labels Dec 18, 2022
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Dec 18, 2022

The language service is entirely too magical... and inconsistent. When hovering over the function, it shows "real" overloads...

image

But when providing arguments, it instead shows "signatures"

image

I think I'm actually going to punt this to plugin-space. I'm really wary of including functionality in TypeDoc itself which significantly changes what you'd see if looking at the declaration file of a library, since it opens up holes for questions when there's now no reference to Entry in the docs for myFunction, or myFunction is rendered with Entry and then also with the expanded signatures (ew, makes it looks like there's an extra overload...)

I might consider this if someone builds a plugin which does this that solves these issues in the rendered docs, but I'm not seeing a clean way of doing it.


If looking to implement this without solving that issue, I'd recommend listening to Converter.EVENT_CREATE_SIGNATURE and replacing sig.parent.signatures with the appropriately expanded signatures. I've just updated the emit for that event to also include the signature, which will be necessary to easily resolve parameter types.

@Gerrit0 Gerrit0 closed this as not planned Won't fix, can't repro, duplicate, stale Dec 18, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improved functionality plugin idea This feature may be best suited for a plugin
Projects
None yet
Development

No branches or pull requests

2 participants