Documentation for fae opened 2 or 3 times. After that it is showing A internal server error occured while generating the documentation.

Module - https/deno.land/x/fae/mod.ts

https://doc.deno.land/https/deno.land/x/abc/http_exception.ts

https://doc.deno.land/https/gist.github.com/lucacasonato/fe3b47180872928b29551a806ca148fd/raw/742d0e0c1de647f163ceec58cd6f4ab1e9f33e24/test.ts is missing the ? in the function argument

Iin dartdoc you can see inherited properties and methods inside of the docs of the class that extends them: https://pub.dev/documentation/path/latest/path/Context-class.html. This is super useful and might be something we want to implement. I think I could probably do that fully client side once we have all required infra for linking types

I feel like we should try to get rid of the snippets underneath the name, but retain all of their useful information. They take up space and contain useless words like export.

I would prefer if this:

looked like this:

This would also allow for clicking thru to the implemented types (if that is needed).

Also this could be used to display for example the abstract keyword if a class is abstract.

Very early draft of JSON output from the doc generator. I'll be filling in gaps as I'm going through AST in detail.

[
  {
    "kind": "Function",
    "name": "foo",
    "snippet": "export function foo(a: string, b: number): void",
    "location": {
      "filename": "./test.ts",
      "line": 10,
      "col": 0
    },
    "jsDoc": "/**\n * Hello there, this is a multiline JSdoc.\n * \n * It has many lines\n * \n * Or not that many?\n */",
    "functionDef": {
      "args": [],
      "return_type": {
        "repr": "void"
      },
      "is_async": false,
      "is_generator": false
    }
  },
  {
    "kind": "Function",
    "name": "bar",
    "snippet": "export function bar(a: string, b: number): void",
    "location": {
      "filename": "./test.ts",
      "line": 15,
      "col": 0
    },
    "jsDoc": "/** This is single line JSdoc */",
    "functionDef": {
      "args": [],
      "return_type": {
        "repr": "void"
      },
      "is_async": false,
      "is_generator": false
    }
  },
  {
    "kind": "Class",
    "name": "Foobar",
    "snippet": "export class Foobar extends Fizz implements Buzz",
    "location": {
      "filename": "./test.ts",
      "line": 20,
      "col": 0
    },
    "jsDoc": "/** Class doc */",
    "classDef": {
      "constructors": [],
      "properties": [],
      "methods": []
    }
  },
  {
    "kind": "Variable",
    "name": "<TODO>",
    "snippet": "export const fizzBuzz: string = \"fizzBuzz\";",
    "location": {
      "filename": "./test.ts",
      "line": 41,
      "col": 0
    },
    "jsDoc": "/** Something about fizzBuzz */"
  },
  {
    "kind": "Interface",
    "name": "Reader",
    "snippet": "export interface Reader {\n    /** Read n bytes */\n    read(buf: Uint8Array, something: unknown): Promise<number>\n}",
    "location": {
      "filename": "./test.ts",
      "line": 46,
      "col": 0
    },
    "jsDoc": "/**\n * Interface js doc\n */",
    "interfaceDef": {}
  },
  {
    "kind": "TypeAlias",
    "name": "NumberArray",
    "snippet": "export type NumberArray = Array<number>;",
    "location": {
      "filename": "./test.ts",
      "line": 52,
      "col": 0
    },
    "jsDoc": "/** Array holding numbers */",
    "typeAliasDef": {}
  },
  {
    "kind": "Enum",
    "name": "Hello",
    "snippet": "export enum Hello {\n    World = \"world\",\n    Fizz = \"fizz\",\n    Buzz = \"buzz\",\n}",
    "location": {
      "filename": "./test.ts",
      "line": 57,
      "col": 0
    },
    "jsDoc": "/**\n * Some enum for good measure\n */",
    "enumDef": {
      "members": [
        {
          "name": "World"
        },
        {
          "name": "Fizz"
        },
        {
          "name": "Buzz"
        }
      ]
    }
  }
]

This would result in showing this:

as this:
.

This would probably be useful for:

• Omit<>
• &

Maybe it would be nice to use @hashrock's "loading" deno for the corner?

constructor, method and property don't have a location

Example link: https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts

On Edge (Classic/EdgeHTML), some content appears and then promptly disappears (never to reappear again). Tested today on Microsoft Edge 44.18362.449.0 (Microsoft EdgeHTML 18.18362).

In dev tools, I see the following exception: "Object doesn't support property or method 'flatMap'". Not sure if this exception related to the "page is blank" problem noted above, but caniuse.com indicates flatMap isn't supported on Edge Classic, which has ~2% of global usage (vs. 0% usage for Chromium-based Edge).

Error:

error: Uncaught AssertionError: Assertion failed.
    at Object.assert ($deno$/util.ts:33:11)
    at compile ($deno$/compiler.ts:1355:5)
    at async tsCompilerOnMessage ($deno$/compiler.ts:1548:22)
    at async workerMessageRecvCallback ($deno$/runtime_worker.ts:74:9)
    at buildDenoLambda (/zeit/5414d56625280cb6/.build-utils/.builder/node_modules/now-deno/dist/index.js:70:15)
    at processTicksAndRejections (internal/process/task_queues.js:94:5)

Refs:

• PR #98
  • Deployment failure https://vercel.com/denoland/doc-website/838yvfwd1
• PR #93
  • Deployment failure https://vercel.com/denoland/doc-website/838yvfwd1

Umbrella issue to track progress on features that are needed to use this project as Deno subcommand.

• AST walking to find exported members for ES module (in the priority order)

  • ExportDecl
  • ExportDefaultDecl
  • NamedExport
  • TsNamespaceExportDecl
  • ExportAll
  • ExportDefaultExpr
  • TsExportAssignment

• finding JSDoc comments for different AST nodes

pub enum Decl {
    Class(ClassDecl),
    Fn(FnDecl),
    Var(VarDecl),
    TsInterface(TsInterfaceDecl),
    TsTypeAlias(TsTypeAliasDecl),
    TsEnum(TsEnumDecl),
    TsModule(TsModuleDecl),
}

Class seems to be the most complex one

• parsing of Comment

  • strip leading *
  • relevant discussion: denoland/deno#4406 (comment)

• output:

  • JSON output
  • text output (should pretty print based on JSON output)

• establish reliable and fast way of testing

These features mustn't be worked on in this repo:

• loading remote files
• CLI parser

(because they are already implemented in Deno and can be easily hooked up once moved to Deno repo)

To consume JSON output we should have some kind of web frontend, while the ultimate goal is to replace Typedoc in Deno API reference.

Let's start small with basic setup and separate components for different kind of docs:
https://github.com/bartlomieju/deno_doc/blob/d6dd7d80bf2ebec306594835d83a28d64c7ac88f/src/doc/mod.rs#L5-L15

All top level objects in JSON output are DocNode structs:
https://github.com/bartlomieju/deno_doc/blob/d6dd7d80bf2ebec306594835d83a28d64c7ac88f/src/doc/mod.rs#L144-L173

Since I'm iterating heavily on the schema of JSON, we can assume that first five fields are shared by all kinds of structs, others are dependent on the kind (and will change heavily).

I did super small webpage in Vue for debugging purposes; it can be seen in script.js and index.html files.

CC @lucacasonato

The API docs are really useful for developers when working with a module. However, this is only part of the picture. Having access to the README.md in the same place as the API docs will give a fuller picture of the capabilities of the API and how to use the API. For example, some of our APIs have no documentation in the code but are well documented in the README.md (example). If a README.md is present in the same directory as the mod.ts, it should linked to somehow.

Some options to include this could be:

• README.md is the default view of the module with the left hand nav links to all the API details (as is)
• Prominently highlight the README.md at the top of the left hand navigation
• Prominently highlight the README.md at the top of the primary display pane

[src] currently links to raw.githubusercontent.com which is, as the name suggests, raw text. It would provide a better user experience if the source could link to the file in the repo instead (e.g. github.com, offering GitHub's code formatting/styling as well as jumping straight to the line number in question.

I think it's not unreasonable to highlight a dozen or so links.

It would be great to eventually have a list of "most often accessed" links

e.g. Date should link to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date

I am taking all the documentation to Spanish in the following repository. https://github.com/FranciscoImanolSuarez/deno_documentacion

I do it for people who speak Spanish but not English.

Hello Community. Recently I found a bug that really caught my attention.
When you enter here: https://doc.deno.land/https/raw.githubusercontent.com/mandarineorg/mandarinets/master/main-core/Mandarine.ns.ts
You will see :

Everything seems ok. It seems like There is namespace called Mandarine, another namespace inside Mandarine called Global, and then another inside global called ApplicationContext and so on and so on. At first, I thought I had coded my code that way, then I was re-looking at it, and the doc website is actually putting my namespaces out of order.
When you check the real file: https://raw.githubusercontent.com/mandarineorg/mandarinets/master/main-core/Mandarine.ns.ts There is no such namespace as Mandarine.Global.ApplicationContext.MandarineCore.Defaults, There is a namespace called Defaults but its not in the order the website is putting it, and for example, the ApplicationContext namespace is not inside global, There is a ApplicationContext namespace but it is in the scope of the mandarine namespace.

Here you can see a picture that explains better what I am talking about.

Class constructors should also have a params: Vec<ParamDef> entry.

• Link in the bottom of sideNav are not visible in Desktops.

screenshot

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

On the other hand the CLI seems to work correctly:

> deno doc https://deno.land/x/oak/mod.ts
Download https://deno.land/x/oak/mod.ts
Download https://deno.land/x/oak/application.ts
Download https://deno.land/x/oak/context.ts
Download https://deno.land/x/oak/send.ts
Download https://deno.land/x/oak/request.ts
Download https://deno.land/x/oak/response.ts
Download https://deno.land/x/oak/types.ts
Download https://deno.land/x/oak/middleware.ts
Download https://deno.land/x/oak/router.ts
Download https://deno.land/x/oak/deps.ts
Download https://deno.land/x/oak/httpError.ts
function composeMiddleware(middleware: Middleware<S, T>[]): (context: T) => Promise<void>
  Compose multiple middleware functions into a single middleware function.

function send(: Context, path: string, options: SendOptions): Promise<string | undefined>
  Asynchronously fulfill a response with a file from the local file system.

class Application
  A class which registers middleware (via `.use()`) and then processes inbound requests against that middleware (via `.listen()`).

class Context

class HttpError extends Error

class Request

class Response

class Router
  A class that routes requests to middleware based on the method and the path name of the request.

enum BodyType

interface Middleware
  Middleware are functions which are chained together to deal with requests.

interface RouteParams

interface RouterContext
  The context passed router middleware.

interface RouterMiddleware

type Body

type HTTPMethods

Some thoughts about single page view

a) scrollable sidebar with list of all nodes (ie. should scroll independent of the rest of page)

b) table of contents; first element visible on the page, all nodes grouped per node kind, all nodes linked to respective card actually not needed, all of that should be in the sidebar

c) node card: current structure looks good, but each card should have an additional child component dependent on node kind, that way, we can customize display for each node

CC @lucacasonato

Add a dark theme. Should respect prefers-color-scheme CSS media query.

https://doc.deno.land/https/raw.githubusercontent.com/pirix-gh/ts-toolbelt-deno-test/master/sources/Object/_api.ts

This is super easy to set up, but might require some changes to caching

It would be great to have a hosted version of deno_doc that you give a URL and it fetches that module, analyzes it, and displays it.

I think there are two reasonable approaches here:

• have a serverless function or server that executes deno doc and responds to the client with the json output
• wasmify the deno doc section of deno and use client side fetch() to fetch code and analyze it with the wasm

The first one is definitely easier, but requires a little bit more maintenance as it needs to be deployed, while the second one will be a lot harder to build, but requires nearly no effort on the deployment side.

I built a demo for the first approach that uses Zeit Now: a combination of static hosting, serverless function hosting and a CDN - https://deno-doc.lucacasonato.now.sh/deno.land/std/http/server.ts. It uses my project now-deno that you can use to deploy serverless Deno functions to Now. I made use of this for the actual backend parser, and just use a slightly adjusted version of the frontend in this repo for the display. The code can be found in this branch: https://github.com/luca-rand/deno_doc/tree/hosted2 (diff). This is still rudimentary, but it works really well.

Is this something that we want? Are there other approaches that might work better?

/cc @ry @bartlomieju

For known URL types (githubusercontent.com, deno.land/x, jspm.io, pika.dev) add a version selector dropdown.

Would be cool if we could share some code with @hayd's udd. Mainly this file: https://github.com/hayd/deno-udd/blob/master/registry.ts.

Here is what I'm imagining:

deno_doc test.ts

const fizzBuzz: string
    Something about fizzBuzz

function foo(a: string, b: number): void
    Hello there, this is a multiline JSdoc.
    It has many lines
    Or not that many?

class Foobar
    Class doc

interface Reader

type NumberArray

namespace Deno

deno_doc test.ts --format json

{ ... }

deno_doc test.ts --format json --output docs.json

Places the generated json to a file at docs.json rather than to stdout

deno_doc test.ts --format html --output docs

Generates a docs folder with the precompiled React application and the generated docs.json.

--output has to be specified.

deno_doc test.ts fizzBuzz

Defined in test.ts:7:0

const fizzBuzz: string
    Something about fizzBuzz

deno_doc test.ts fizzBuzz --format json

{
    "kind": "variable",
    "name": "fizzBuzz",
    "snippet": "export const fizzBuzz: string = \"fizzBuzz\";",
    "location": { "filename": "test.ts", "line": 7, "col": 0 },
    "jsDoc": "Something about fizzBuzz",
    "variableDef": {
      "tsType": { "repr": "string", "kind": "keyword", "keyword": "string" },
      "kind": "const"
    }
}

deno_doc test.ts foo

Defined in test.ts:23:0

function foo(a: string, b: number): void
    Hello there, this is a multiline JSdoc.
    It has many lines
    Or not that many?

deno_doc test.ts Foobar

Defined in test.ts:33:0

class Foobar
    Class doc

constructor constructor(name: string)
property protected protected1: number
property public public1: boolean
property public2: number
method foo(): Promise<void>
method bar(): void
    Sync bar method

deno_doc test.ts Foobar.bar

Defined in test.ts:36:0

bar(): void
    Sync bar method

ect... - the "titles" should match the titles on the webpage, and the "body" should look similar to the card content on the webpage.

Everything should be nicely colored.

This is similar to how Go displays things.

Ideas?

/cc @bartlomieju

Clicking [src] link in runtime documentation downloads the file.

This problem does not appear for third party docs.

https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts#Deno.chmod

So make the Deno.ListenOptions type clickable and redirect to https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts#Deno.ListenOptions. This can be handled fully client side.

A related super complicated thing would be to make the Reader type clickable and redirect to https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts#Deno.Reader. This is super complicated because Reader is actually an alias to Deno.Reader. The only really possible way of doing this (which would be complex) is for deno doc to add a field to all type_ref TS types which would give the resolved global scope location to that type (so that Reader would have Deno.Reader as its resolved type)

/cc @bartlomieju

Couple of thoughts:

• line and column are not part of the link - effectively all links on the whole page link to the same thing - it would be great to format them as <url>:<line>:<col>
• wrapping link in single quote '<url>' is not very readable - I'd prefer it was underlined - visible and accessible
• the whole link takes a lot of space - especially for long URLs - I like how docs.rs solves this problem by showing [src] link in the right-hand side corner:
  

when I start here: https://deno.land/std/http/README.md, and click DOCUMENTATION in the top left I see an error page:

I can see that this api request https://doc.deno.land/api/docs?entrypoint=https%3A%2F%2Fdeno.land%2Fstd%2Fnode%2FREADME.md is returning a 500 with this error message

{"error":"Download https://deno.land/std/node/README.md\n\n"}

I'm assuming it's because the server doesn't know how to generate docs from a non-ts file but the error message could be better, it was very confusing for me as a first time user.

like doc.rs has

1. In the typedoc, there's icons by each link representing what it is
2. Having everything as Deno.<insert name here> instead of having say under a category, i.e. https://discord.coffee/4WGJsKj.png, looks sort of messy in my opinion.
   2a. Having the stuff split into multiple sections while still under the same namespace is confusing, i.e. Deno.file is listed under Classes, but is still part of the same Deno name space, the first point would allow unifying them under a single category while still representing what they are.
3. The ability to only show certain things, i.e. https://discord.coffee/3bVdc8L.png

Currently absolute positioning is used for the overall site layout, this is bad and breaks on devices with smaller safe areas than viewport size. Should move to flex (or grid).

This includes fixing the scroll issues.

Opening for tracking purposes.

Web frontend should display TS types in such a way, that they can be interlinked with other presented structures.

https://doc.deno.land/https/raw.githubusercontent.com/pirix-gh/ts-toolbelt-deno-test/master/sources/index.ts

JSDoc can contain markdown snippets with example. They should be rendered accordingly. It will require to pre-parse and clean JSDoc in Rust to get rid of comment markers (*). Note to self: whitespaces should be preserved.

If we want to add features such as #37 or a source file display as requested by @bartlomieju it might be better if we increase the scope of this site. Go moved from a simple documentation only site, https://godoc.org, to https://pkg.go.dev, a site is meant to give a complete overview for a given package.

Because our module system is decentralized we can't offer everything that pkg.go.dev does, but we can do a lot of things for any old URL, and offer some extra features for certain known providers like github, pika or jspm.

Some ideas:

• documentation
• source code view (with clickable references)
• dependency tree (pretty much deno info output)
• version list (for selected pages -> github, pika, jspm, ect)

This would make for a really nice and organized way for developers find info about any modules they are importing.

This might also be better suited as a third party thing, rather than a deno thing. What are your opinions?

Also related to #52 and #53

[src] opens in a new tab/window which can be a slightly jarring experience and may mean going back and forth between the source and the docs. One suggestion would be to have [src] expand an inline iframe with the source in it. Example:

Having another link to open in a new tab/window would also be good.

I would like to start translating Deno's documentation into Portuguese. Is there an incentive for that? How can I get started? After I translate where do I open a PR?

Currently we just display the first one, we should display all overloads.

Not entirely sure what the purpose of the URL here in the doc:

Can probably borrow the same implementation as what we have in the actual website and have 'raw' and 'repository' somewhere:

The link to the hand-drawn logo responds with a 404

On the documentation page on doc.deno.land (for example, this) the main content is inside a wrapper div, which has an overflow rule, leading to scrolling inside the div instead of the body.

Would it be possible to have this converted to make it so the sidebar and header are sticky and the content scrolls like you normally would instead of in a nested div? This would make it so you could also scroll when your mouse is on the header, and also makes it so the site is more accessible on iOS.