denoland / docland Goto Github PK

In ESM, JSDoc @typedef types are not documented as exported types from the module.

This also means JSDoc links to @typedef types are not rendered as links.

For example:

• https://doc.deno.land/https://unpkg.com/[email protected]/Cache.mjs
• https://unpkg.com/[email protected]/Cache.mjs

The CacheEventMap, CacheEventSetDetail, CacheKey, CacheValue, and CacheStore types should be documented but are not.

Click on [src] link in https://doc.deno.land/deno/stable/~/AbortController.

This was solved in the v1 of the doc website by linking to https://doc-proxy.deno.dev/builtin/stable instead of the GH download.

In https://doc.deno.land/https://deno.land/x/[email protected]/mod.js/~/Importer#fakeModule for example, it shows up as

fakeModule(url, moduleImplementation)

even though in the source the parameter types are provided via jsdoc:

/**
 * Fakes a module.
 * @param {string | URL} url should be relative to the `importMeta` argument
 * provided in the {@link constructor}.
 * @param {string} moduleImplementation The code to replace the imported content with.
 */

If a class has instance properties or methods created within the constructor, they should be documented but currently are not.

For example, the Cache class instance property store should be documented:

• https://doc.deno.land/https://unpkg.com/[email protected]/Cache.mjs/~/default
• https://unpkg.com/[email protected]/Cache.mjs

Decorators are in the doc nodes, they are just not rendered as part of the documentation

This page returns an internal server error: https://doc.deno.land/https://deno.land/x/[email protected]/mod.ts/~/Command

The sidebar on the previous design was super helpful. While reading the docs of any specific item, I would usually quickly scroll the sidebar for something else if I didn't find what I was looking for. Nice and clean new design btw.

The "doc proxy" Deploy script is actually part of the old doc website source: https://github.com/denoland/doc_website/blob/HEAD/deploy/main.ts

We currently use it as a page as a src link for the built-in APIs. We should just integrate this into this repo and then we should be able to decommission the doc_proxy deploy script.

Not sure if this is the write repo to file this issue...

In the new updated docs at: https://doc.deno.land/deno/stable/~/Deno.run
It shows that it returns a Process<T> but Process is no longer a hyperlink to the docs page for that type, so I have to manually go back and find the Process type manually.

In the old stable docs, if you looked at Deno.run, you could click on Process to be taken to the docs for that type.

For newbies like myself, being able to click those custom types and see what they are was very useful.

I would like to see doc.deno.land supporting @example tag – https://jsdoc.app/tags-example.html.

Example of using such tag:

• https://github.com/Im-Beast/deno_tui/blob/7ab514cb31abb9ac96f509fde2942a0851b161bb/src/event_emitter.ts#L43

https://doc.deno.land/https://deno.land/x/[email protected]/index.ts

https://deno.land/x/[email protected]/jwe/compact/encrypt.ts#L10-L23

The old doc site provided linkages to globally scoped symbols, the Deno namespace linked to the documentation website otherwise it linked to MDN.

This is due to the import.meta.url changes and static file middleware needs to be updated to use Deno.readFile.

The fully rendered images should be cached in memory, like the doc nodes are as well as an expires cache header should be set.

https://doc-land.deno.dev/deno/stable ->
https://doc-land.deno.dev/deno/stable/~/Deno ->
https://doc-land.deno.dev/deno/stable/~/Deno.connect

Any chance we could get a toggle in a follow up?

Originally posted by @bartlomieju in #41 (review)

https://doc.deno.land/https://deno.land/[email protected]/encoding/toml.ts

add a dark mode theme

JSDoc links to a default import render with an incorrect URL.

For example:

• https://doc.deno.land/https://unpkg.com/[email protected]/cacheDelete.mjs
• https://unpkg.com/[email protected]/cacheDelete.mjs

This Cache link:

Incorrectly goes to:

When it should go to:

interfaces properties appear in the order declared, not alphabetically

Ideally there would be a way to specify, perhaps in a URL parameter, an import map that goes along with the documented module.

There could be UI to tweak the import map, which would update the parameter in the URL and regenerate the docs.

For example, the docs for this module breaks due to the bare react import specifier:

https://doc.deno.land/https://unpkg.com/[email protected]/waterfallRender.mjs

That module works great in Deno projects with an import map that assigns a Preact ESM URL to the react specifier.

I would absolutely 😍 love 😍 to be able to just link to Deno docs in the readme for all my universal Node.js/Deno packages that rely on import maps, instead of maintaining complicated API docs markdown by hand. Hardcoded docs can have mistakes that get permanently published for that package version; whereas having docs generated on demand allows them to just get better and better over time as Deno docs improves, for all versions of the package.

This is because we try to concatenate the text and strip it of the markdown. This means the code block gets stripped of its newlines and therefore gets treated as one big block of text.

I want to see parameter types for Deno.chmod API.

To do that I go as follows:
https://doc-land.deno.dev/ -> click "Deno CLI APIs (stable) ->
https://doc-land.deno.dev/deno/stable -> select "Deno" namespace ->
https://doc-land.deno.dev/deno/stable/~/Deno -> select "chmod" function

This requires to go through 3 separate pages to see it.

I think I'd be nice if there was any indication about argument types on the page for "Deno" namespace.

We should integrate it into Google Analytics to provide better insight on what documentation folks are looking at and help identify any rending issues.

Ping @piscisaureus

The following causes a 500: https://doc.deno.land/https://cdn.skypack.dev/@firebase/firestore?dts/~/PartialWithFieldValue

These seem very minor, but just for kicks I ran a link checker I wrote on https://doc.deno.land/deno/stable (mostly to test it out) and it found two links pointing to nonexistent fragments:

1. https://doc.deno.land/deno/stable/~/Deno -> #Namespaces

This seems straight forward. If there's only a single namespace, the heading's id is "Namespace" instead of "Namespaces" but the link in the sidebar is always to "#Namespaces".

2. https://doc.deno.land/deno/stable/~/Deno.chmodSync -> #Deno.chmod

I don't understand the context well enough to assess the problem. deno.d.ts uses Markdown in the JSDoc comment. I'm not sure if this is allowed or not (if it is, then I guess the doc generator should handle this somehow; if not, then the JSDoc comment shouldn't use Markdown).

Link checking during CI?

Related: @bartlomieju raised the idea on Discord of integrating link checking into docland's CI process. I'm wary of introducing something like this because it could fail on upstream problems (potentially the second issue here), leading to unwanted downstream breaks. But it's possible I'm too cautious (and honestly, I've never used GitHub Actions, so I'm not sure how rock-solid each step needs to be).

Regardless, feel free to leave feedback on that idea here. I didn't want to open a separate issue for that until I was confident that the issues above are in fact real bugs in the docs/generator (as opposed to bugs in my admittedly-not-thoroughly-tested tool :).

JSDoc @see tags are widely used, are supported by TypeScript in VS Code, and should display in rendered docs but currently don't.

For example:

• https://doc.deno.land/https://unpkg.com/[email protected]/Cache.mjs/~/default
• https://unpkg.com/[email protected]/Cache.mjs

The JSDoc @see tag should be in the rendered docs but is missing:

path.parse is listed in readme, but I can't find it from doc.deno.land.

Is it expected behavior?

https://doc.deno.land/https://deno.land/x/[email protected]/mod.ts

I'm always getting this when trying to load docs from this URL: https://code.harmony.rocks/v2.4.0 (or from the https://deno.land/x/harmony module in general):

The old page uses links like: https://doc.deno.land/https/deno.land/x/redis/mod.ts

The new page uses links like: https://doc-land.deno.dev/https://deno.land/x/redis/mod.ts (which I think is better 💯 )

We should have a redirect from the old scheme to the new one, so old links still work.

https://doc.deno.land/deno/unstable/~/Deno.DynamicLibrary

The old docs website supported the JSDoc @link syntax. Reference: https://jsdoc.app/tags-inline-link.html

This is a feature request for equal support of this directive on the new Deno docs website.

References:

• Location of pertinent code on old docs site: https://github.com/denoland/doc_website/blob/41eef09684f7fc33f8930f93ca2caa2881c39036/components/JSDoc.tsx#L15

Loosely related:

• denoland/doc_website#205
• denoland/doc_website#228

The doc svg badge no longer works:

https://doc.deno.land/badge.svg

Example use: https://github.com/oakserver/oak/blob/main/README.md

Not sure if you guys have noticed, but https://doc.deno.land/ is down for half a day now. Only gives a 502 because the deployment failed. Is there anyone working on getting this fixed?

I put a markdown hyperlink syntax into a doc comment, and doc.deno.land parsed and linked the text, but there is no styling to indicate that the link is present, even on hover. I'd want to see e.g. underline at all times, to point out that a link is available in the block of text.

As a simple example, there's a link after "For more information" below:

Permalink repro: https://doc.deno.land/https://aws-api-7b9dvns8xscg.deno.dev/v0.2/services/sns.ts?actions=GetEndpointAttributes&docs=full/~/SNS#getEndpointAttributes

Code is something like:

  /**
   * Retrieves the endpoint attributes for a device on one of the supported push notification services, such as GCM (Firebase Cloud Messaging) and APNS.
   * For more information, see [Using Amazon SNS Mobile Push Notifications](https://docs.aws.amazon.com/sns/latest/dg/SNSMobilePush.html).
   */
  async getEndpointAttributes(...) {...}

This example isn't so bad, but EC2.RunInstances has 8 hyperlinks across a full page of text and they are not easy to find.

EG
https://doc.deno.land/doc?url=https%3A%2F%2Fraw.githubusercontent.com%2Fremix-run%2Fremix%2Fmain%2Fpackages%2Fremix%2Findex.ts

When using a long URL as a source for the code, the URL (when rendering embed), will go out of the border, making it no further readable. In my opinion it would be good to add URL wrap.

This is the issue

denoland/deno_doc#215

I created my module colormath.js but I wanted it to support in Node.js, Deno and Browser so i decided to use tsup for bundling ts files and here is my code for mod.ts:

// @deno-types="./dist/index.d.ts"
export * from './dist/index.mjs';

Now, I published this module in deno (colormath) but if you check the documentation in

https://doc.deno.land/https://deno.land/x/colormath/mod.ts

Although the documentation has parsed all functions, type aliases, classes but has only one namespace?
The documentation did not parsed all namespaces?

Is there any fault on my side?

On the page /deno/stable Deno.resolveDns is missing the little text about what it does.

While it should have a summary text as seen here

Classes that are default exports incorrectly render with the name default instead of what their name actually is.

For example:

• https://doc.deno.land/https://unpkg.com/[email protected]/Cache.mjs/~/default
• https://unpkg.com/[email protected]/Cache.mjs

https://doc.deno.land/deno/stable/~/URLPattern

I released a new version of my code but docland didn't pick it up yet when I visit the URL without a version in it. It'd be nice to have it auto-redirect to the latest version whenever someone navigates to the URL without a version in it.

e.g. https://doc.deno.land/https://deno.land/x/xnd/_index.ts → https://doc.deno.land/https://deno.land/x/[email protected]/_index.ts (currently)

Browsing on a mobile device documentation is quite common. We should have a responsive design for the website.

It's very hard for me to distinguish colors used in "Namespace" and "Classes" sections due to colorblindness:
https://doc-land.deno.dev/deno/stable/~/Deno

(these are actually the two colors I have troubles with so it's just a bad coincidence, but hopefully we can make them more accessible)

https://doc.deno.land/https://deno.land/x/[email protected]/mod.ts/~/Filter returns Internal Server Error

I'd like to be able to have a single docs page for all my many modules in my repository. I currently use a _index.ts (I suppose I could name it _mod.ts instead). This works fine but I'm wondering if there might be a different way to do this that doesn't involve create a private/internal module that creates a directory of all my other modules manually.

e.g. could support be added to use some kind of pattern glob or something similar?

/static/ contains generated version of the documentation nodes and /build.ts updates these. When a Deno tag is released, it should be possible to automate the build and update of these files.