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.

Sign up for GitHub

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

Jump to bottom

Documenting transitive types in API/symbols? #165

Open
arv opened this issue Mar 4, 2024 · 2 comments · May be fixed by #591
Open

Documenting transitive types in API/symbols? #165

arv opened this issue Mar 4, 2024 · 2 comments · May be fixed by #591
Labels
docs gen Related to the documentation generation

Comments

@arv
Copy link

arv commented Mar 4, 2024

I was browsing the @badrap/valita symbols and the generated API docs and I see a lot of symbols are not linked/documented.

For example:

https://jsr.io/@badrap/valita/doc/~/ArrayType#method_func_0

func(arr: unknown, flags: number): RawResult<ArrayOutput<Head, Rest>>

Here neither RawResult nor ArrayOutput are linked or documented. These two type definitions are not exported by src/index.ts so it is understandable that they are not linked. But, to make things useful the reader of the API docs would want to see what these types are even if they cannot be imported directly.
@marvinhagemeister marvinhagemeister added bug docs gen Related to the documentation generation labels Mar 4, 2024
@lucacasonato lucacasonato added this to JSR Mar 4, 2024
@github-project-automation github-project-automation bot moved this to Needs Plan in JSR Mar 4, 2024
@lucacasonato lucacasonato moved this from Needs Plan to Needs Triage in JSR Mar 4, 2024
@lucacasonato lucacasonato moved this from Needs Triage to Needs Plan in JSR Mar 5, 2024
@crowlKats crowlKats removed the bug label Mar 5, 2024
@crowlKats crowlKats linked a pull request Jun 3, 2024 that will close this issue
Open
@crowlKats crowlKats moved this from Needs Plan to Ready in JSR Jan 17, 2025
@crowlKats crowlKats moved this from Ready to In Progress in JSR Jan 17, 2025
@nicolo-ribaudo
Copy link
Contributor

It'd be great if JSR did this, as there are many cases where the type doesn't need to be exported. One example is https://jsr.io/@babel-test-6ae45912/[email protected]/doc/~/parse.

Being forced to export the types just so that JSR can document them leads to bad DX, as all those types would show up in auto complete when importing the package.

If the decision is to keep not showing docs for these non-exported types, then JSR should probably error when trying to publish a package that refers to an internal type as part of the public interface. In this case, it's still be great to have an opt-in /* @jsr-pretend-that-this-is-exported */ comment.

@crowlKats
Copy link
Collaborator

@nicolo-ribaudo we will definitely still do this; I just need to sit down and finish the PR linked to this issue. Not sure when I will get the chance to do that though

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs gen Related to the documentation generation
Projects
JSR
Status: In Progress
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

fix(docs): generate pages for internal symbols jsr-io/jsr
4 participants
@arv @marvinhagemeister @nicolo-ribaudo @crowlKats