[HN Gopher] Tsdocs.dev: Type docs for any JavaScript library
___________________________________________________________________
Tsdocs.dev: Type docs for any JavaScript library
Author : webartisan
Score : 146 points
Date : 2023-12-19 16:34 UTC (6 hours ago)
(HTM) web link (tsdocs.dev)
(TXT) w3m dump (tsdocs.dev)
| waldofind wrote:
| Looks like rust inspired (docs.rs) but for the typescript
| ecosystem. Neat!
| radicalriddler wrote:
| I saw this on twitter a week or two ago and that's exactly how
| he explained the purpose
| conandole wrote:
| A good example of a well documented library is three.js
|
| https://tsdocs.dev/docs/three/0.159.0/classes/Bone.html
|
| It's fun to just read through all of the different entities in
| the 3D ecosystem, even though I've only used it only a couple of
| times.
| prideout wrote:
| Agreed although I'm somewhat confused since the three js source
| code is JavaScript not TypeScript.
| WorldMaker wrote:
| It is auto-redirecting to the @types/three package and
| getting the types from DefinitelyTyped. You can see that in
| the breadcrumbs, but it might be something that could be
| better highlighted (and maybe even redirect the URL to make
| even more obvious to developers).
| _the_inflator wrote:
| Great reference.
|
| To this date, one of the best well-documented code is jQuery:
| https://github.com/jquery/jquery/blob/main/src/core/init.js
|
| I learned a lot from looking into the code.
| montyanderson wrote:
| It might have just received the hug of death. Otherwise, this is
| fantastic; I've been looking for something like this.
| teaearlgraycold wrote:
| Should get those bytes on a CDN!
| pastelsky wrote:
| Author here:
|
| I created this because I found myself peeping inside type
| declaration files too often, and the only way to do that was by
| installing the package first.
|
| tsdocs.dev helps you check the API surface of a good number of JS
| libraries and their past versions -- usually a quick search away.
|
| There's something powerful about speed and being able to answer
| questions in seconds that usually take minutes.
|
| edit: The server might be overloaded with requests as we prime up
| our caches, but do visit back after HN's done hugging us to
| death.
|
| You can show your support and help cover a part of server costs
| if this (or bundlephobia.com) saved you time.
|
| https://github.com/sponsors/pastelsky
| karpour wrote:
| Congrats, this looks fantastic and will be useful for many!
| WorldMaker wrote:
| Found a fun error "TypeDefinitionResolveError" for a package
| that includes Typescript sources. Best guess, it may be related
| to the package.json uses a modern "bare" exports field
| ("exports": "./index.js"; no "main", no "types") where
| "index.ts" exists in the package as well. (Not a lot of
| projects use this today, but it is a modern way to publish
| projects that will likely increase.)
|
| Typescript itself works just fine with this with this type of
| package with "moduleResolution": "node" (tsconfig/CLI options)
| with recent version using recent enough ES targets or with
| "moduleResolution": "node16" in older versions/older ES
| targets/non-ES targets.
|
| https://tsdocs.dev/search/docs/butterfloat
|
| Hope that's useful enough to debug the error.
| maxloh wrote:
| There isn't a LICENSE file in the repo.
|
| Can you add one?
| spankalee wrote:
| This is really awesome work!
|
| This takes a big burden off of individual packages from
| publishing their own API docs (having done that I know how hard
| it can be!), and having a centralized API viewer can offer a
| lot of advantages over separate docs.
|
| A couple of things I would suggest:
|
| 1. Track re-exports and cross-package references and allow
| crossref links to go into other packages. If package A uses
| rxjs, then links to the rxjs types should go to the canonical
| definitions in the rxjs package. (figuring out the canonical
| declaration can be tricky because it's not always the original
| declaration though)
|
| 2. Organizing by type isn't always a great introduction or way
| to navigate a package. On the Lit project at
| https://lit.dev/docs/api we re-organized the API docs by
| categories and the most important API surfaces. There aren't
| standard jsdocs for this, but a few straightforward things like
| @category could be used to offer an alternate top-level nav for
| a package. Also consider supporting the @packageDocumentation
| tag from tsdoc.
|
| 3. Consider showing files other than the README. Relative links
| to things like CONTRIBUTING.md currently break. Alternatively
| interpret all relative links as pointing to github.com or
| npmjs.com. It'd be great to have a way to link from the README
| into API docs to guide readers. The community doesn't have a
| great convention for this unfortunately.
| pastelsky wrote:
| > 1. Track re-exports and cross-package references This
| should already be tracked -- play around with the member
| visibility widget on the sidebar for e.g. For convenience,
| I've inlined the types from re-exports, but might be a good
| idea to indicate they were re-exported.
|
| Pointing to the canonical source can also limit the
| usefulness in a few cases (e.g. d3 is just a bunch of re-
| exports), and users may not care about internal package
| organization.
|
| > 2. consider supporting the @packageDocumentation tag
| Organizing by @category and @packageDocumentation should
| already be supported. e.g. See the functions in --
| https://tsdocs.dev/docs/lodash-es/4.17.21/index.html
|
| > 3. Relative links to things like CONTRIBUTING.md currently
| break Yeah, this is known, thanks!
| https://github.com/pastelsky/tsdocs/issues/9
| zebracanevra wrote:
| Does this service do anything different/better than jsdocs.io?
|
| I like the way jsdocs.io puts everything on one page.
|
| I was initially confused when I looked up a package on
| tsdocs.dev and just got the readme. The actual type defs were
| tucked away out of sight in the hamburger menu. May just be a
| problem with the mobile site.
| wruza wrote:
| Hi, nice site! I found a small ux issue on ios: the search
| field has capitalization on by default. It can be turned off
| with https://stackoverflow.com/a/5171812
| WorldMaker wrote:
| Some quick bits of feedback after a small bit of skimming
| (between bad gateway errors, sorry for contributing to all the
| over-traffic):
|
| - It would be great to see some of the fields from package.json
| shown as an overview above/next to the README of packages. The
| homepage and repository fields in particular are often quite
| useful to have quick access to. You could pull up npmjs.com
| directly next to this site, but it might be nice to have it all
| in one place.
|
| - In cases where there is an auto-redirect from package-name to
| @types/package-name it might be nice to still show the README
| (and package.json metadata if added) of the original package-
| name.
|
| - Typedoc upstream includes a dark theme and does the prefers-
| color-scheme auto-setup. This might be nice to have here, too.
| matsz wrote:
| > it might be nice to still show the README (and package.json
| metadata if added) of the original package-name
|
| This would be great, @types/* docs are rarely ever useful.
| Although it'd be still nice to indicate that the types are not
| available in the original package.
| esamatti wrote:
| This is awesome! Thanks for sharing.
| jjice wrote:
| This is great, bookmarked. I hope we can see this in search
| results in the future.
|
| I started a new job in TypeScript back at the beginning of the
| year and the lack of standardized library documentation viewing
| is a surprising gap in the TS ecosystem. This is great, thank
| you!
| whoisthemachine wrote:
| This is a better looking version of what Java and C# have had for
| a long time (kudos to the author for that!), is that the
| inspiration for this tool?
|
| https://docs.oracle.com/javase/8/docs/technotes/tools/window...
|
| https://dotnet.github.io/docfx/
|
| I saw the author mentioned in another comment that they found
| themselves peeping inside type declaration files "too often".
| While I do often use sites generated by the above tools to
| discover new API's that suit my needs, diving into the actual
| code using a good decompiler is still my first move, as it is
| often cheaper than seeking out the documentation online, and it
| will show me the actual implementation as well. So in my opinion
| there is no shame in looking inside the declaration files!
| turboturbo wrote:
| For `@remix-run/react`, I get the following error:
|
| UNEXPECTED_DOCS_POLL_FAILURE 500
| {"statusCode":500,"error":"Internal Server
| Error","message":"Cannot read properties of undefined (reading
| 'changePriority')"}
| ttyyzz wrote:
| Bad gateway / Error code 502
| jstasiak wrote:
| Looks like a great initiative - I wish there was a reliable TS/JS
| equivalent of https://docs.rs (even considering rustdoc's
| deficiencies[1]).
|
| I went through this exercise recently and so far my experience
| with trying to produce documentation from a somewhat convoluted
| TS codebase[2] has been disappointing. I would claim it's a
| consequence of the library's public (user-facing) API
| substantially differing from how the actual implementation is
| structured.
|
| Typedoc produces bad results for that codebase so sphinx-js,
| which I wanted to use, doesn't have much to work with. I
| ultimately documented things by hand, for now, the way the API is
| meant to be used by the user.
|
| Compare:
|
| https://ts-results-es.readthedocs.io/en/latest/reference/api...
|
| vs
|
| https://tsdocs.dev/docs/ts-results-es/4.1.0-alpha.1/index.ht...
|
| https://www.jsdocs.io/package/ts-results-es#package-index
|
| [1] https://github.com/rust-lang/rust/issues/66249
|
| [2] https://github.com/lune-climate/ts-results-es
___________________________________________________________________
(page generated 2023-12-19 23:00 UTC)