Add @category JSDoc tag to improve reference docs generation

[schickling]

When generating reference docs (e.g. via Paka 🦙) it can be very helpful to mark exports with the @category JSDoc tag which enables grouping them in a semantically more meaningful way.

Here are a few example packages which already added the @example JSDoc tag:

• graphql-ws
• @antfu/utils

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

[kirillgroshkov]

Sorry for offtopic, @schickling, do you know how I can get my packages listed on paka.dev? https://paka.dev doesn't show much and I can't even google-find anything about this Paka (which looks like a fantastic tool that I'd use!)

[sindresorhus]

@schickling I noticed that Paka doesn't show the Template Literals category:

https://github.com/sindresorhus/type-fest/blob/main/ts41/camel-case.d.ts#L64

Either because it has a space in the name or because the type is conditional:

type-fest/package.json

Lines 44 to 50 in 9f4817e

	"typesVersions": {
	">=4.1": {
	"*": [
	"ts41/*"
	]
	}
	},

Paka should show all types and assume the latest TypeScript version.

[schickling]

Sorry for offtopic, @schickling, do you know how I can get my packages listed on paka.dev? https://paka.dev doesn't show much and I can't even google-find anything about this Paka (which looks like a fantastic tool that I'd use!)

Paka is not yet officially launched but currently in the process of increasing its feature and package coverage. If you're interested in using Paka I'd be excited to chat more. Maybe you want to send me a DM on Twitter?

[schickling]

Either because it has a space in the name or because the type is conditional:

type-fest/package.json

Lines 44 to 50 in 9f4817e

	"typesVersions": {
	">=4.1": {
	"*": [
	"ts41/*"
	]
	}
	},

Paka should show all types and assume the latest TypeScript version.

That's a great point @sindresorhus. Seems like Paka doesn't yet support typesVersions properly. Will be fixed soon! 🤞

[sindresorhus]

@schickling Are you still working on Paka? If so, would you be able to add https://github.com/sindresorhus/ts-extras ?

[schickling]

@schickling Are you still working on Paka? If so, would you be able to add https://github.com/sindresorhus/ts-extras ?

Yes, still working on it and steadily making progress. Just a pretty complex problem in general :)

Re the package you've asked about. Did you already check this link? https://paka.dev/npm/ts-extras/v/0.1.0

Note: Unfortunately in some cases types imported/exported from other dependent packages results in the type being displayed as any. This is a pretty tough problem to solve but @jasonkuhrt is working on it.

[sindresorhus]

Ah, nice. I thought packages has to be whitelisted.

---

Note: Unfortunately in some cases types imported/exported from other dependent packages results in the type being displayed as any. This is a pretty tough problem to solve but @jasonkuhrt is working on it.

That is a big downside for my use-case as I plan to import a lot of types from an external package. Good to hear you're working on it though.

[jasonkuhrt]

TS 4.5 has some improvements coming that will make distinguishing different kinds of any (explicitly written by author, failed to resolve, etc.) better. It might help, but yeah, we've currently hit some relatively high walls with TS on this issue. The problem is that solving this is a combination of the AST + type checker, as the typechecker alone does not preserve info about the any such as where it is in the AST or how it came to be (again TS 4.5 might improve this). The consequence is that deep in our recursion we need to bring in AST info where currently today we have none. Its a big architectural change to start to tackle this in a general way. What we have today is some special-cases paths, but far from general solution (we discovered later how hard general would be).

Hope that makes sense.

One thing I should add those is both @schickling and I recognize how killer of a feature cross-package type reference tracking is. :)

[sindresorhus]

Thanks for elaborating. Too bad you cannot just reuse what VS Code uses to power its type hints.

[jasonkuhrt]

In VSC the same thing happens unless you have run npm install. We don't do that in Paka during extraction on the basis that doing so is too heavy in a request context.