JSDoc

[yusukebe]

What is the feature you are proposing?

We haven't written JSDoc for the Hono code. I used to think that maintaining JSDoc would be troublesome, especially since we also have a website. However, now that the API is mostly stable, it's a good time to start. We don't need to write extensively in JSDoc, but including the basics would be beneficial.

[zisra]

Thoughts on the proposed TSdoc standard?

[yusukebe]

@zisra

Ah, TSDoc seems promising. We should consider to write docs using TSDoc.

[yusukebe]

Can anyone help with this? :) I believe it's a good starting point for the middleware documentation.

[yudai-nkt]

maintaining JSDoc would be troublesome, especially since we also have a website.

TypeDoc (optionally with typedoc-vitepress-theme for use with VitePress) can generate API documentation from JSDoc. Maintaining two documentation sources should generally be avoided because they can easily get out of sync.

If we need fined-grained control on how API reference would like, Faker.js is a good example (docs and its source).

[yusukebe]

Ah, great. Faker.js docs is so cool!

[vadhe]

I will try to help with this but, I don't know how to run local doc(https://hono.dev/). Could you please guide me on how to run the docs in localhost?

[zisra]

@vadhe

git clone https://github.com/honojs/website hono-website
cd hono-website
npm install 
npm run dev

Then, open the link give to you

[vadhe]

thanks, @zisra, it turns out separate repo

[goisaki]

I may be able to help.
I have tried to prepare to write TypeDoc in this branch.

$ git clone -b feat/plan-#1338-add-typedoc [email protected]:nabeken5/hono.git hono-typedoc-demo && cd hono-typedoc-demo
$ yarn
# Add a TypeDoc somewhere and add the path to that file to the entryPoints in typedoc.json
$ yarn typedoc:build

Edit:
Demo also added (in a separate branch)

/**
 * `RegExpRouter` is a class that implements the `Router` interface.
 * Find the route using a regular expression.
 *
 * @example
 * ```typescript
 * const router = new RegExpRouter();
 * ```
 */

and some TypeDoc (this is an example, By GPT-4

Since the VitePress root is not in honojs/hono, it seems difficult to add it directly to hono.dev. (make it monorepo...?).
I set it up to be generated in docs/api instead.
Adding a link from hono.dev here would solve the problem.
If this method is ok, I will create a PR and TypeDoc roadmap issue.

(@vadhe sorry if you have already proceeded. I couldn't find it)

[yusukebe]

@nabeken5

Thanks.

Hmm. I'd like to include the API docs generated into hono.dev and I don't want to make this project as a monorepo.

[goisaki]

How about copying honojs/hono/docs/api in the GitHub Action cron for hono/website?
If I can, I'll try it today.

[vadhe]

I may be able to help. I have tried to prepare to write TypeDoc in this branch.

$ git clone -b feat/plan-#1338-add-typedoc [email protected]:nabeken5/hono.git hono-typedoc-demo && cd hono-typedoc-demo
$ yarn
# Add a TypeDoc somewhere and add the path to that file to the entryPoints in typedoc.json
$ yarn typedoc:build

Edit:
Demo also added (in a separate branch)

/**
 * `RegExpRouter` is a class that implements the `Router` interface.
 * Find the route using a regular expression.
 *
 * @example
 * ```typescript
 * const router = new RegExpRouter();
 * ```
 */

and some TypeDoc (this is an example, By GPT-4

Since the VitePress root is not in honojs/hono, it seems difficult to add it directly to hono.dev. (make it monorepo...?). I set it up to be generated in docs/api instead. Adding a link from hono.dev here would solve the problem. If this method is ok, I will create a PR and TypeDoc roadmap issue.

(@vadhe sorry if you have already proceeded. I couldn't find it)

no worries, I didn't continue this because it separate repo

[goisaki]

Hmmm, this is difficult because there are few issues.

1

If honojs/hono generates documents in docs/api, the basePath will be docs/api in the typedoc-sidebar.json generated by typedoc-vitepress-theme.

const basePath = path.relative(sourceDir, outDir);

from typedoc-plugin-markdown

In honojs/website it should be api/, so it doesn't work.

2

api/ is already in use.

---

1 can be solved by rewriting it in GitHub Action.
(but not so cool)
2 can be solved by copying the current document to TypeDoc.
In the meantime, there is a way to add a new api/typedoc or something.

Please advise.

[yusukebe]

@nabeken5

Please hold off for a while as I'd like to give this some thought. Our main purpose is not creating API documentation for the website, but to write JSDoc in the code. I'm currently inclined to think that it's better to include minimal information in the source code and provide more detailed information on the website.

[goisaki]

I’m for.
If we make the current hono.dev API Docs more rich, and the TSDoc has a simple description, @param, @return, @example or so, the DX is perfect!

[goisaki]

Hi @yusukebe
https://oslo.js.org/
I think this API documentation is cool.
Maybe Hono could do something like this too?
(new function based page)
I'll write about it if you want.

[yusukebe]

@nabeken5

Is the current documentation, such as here, not enough?

[goisaki]

@yusukebe I want to split a page by function (or method) and group them by package.

[yusukebe]

Hmm. I think we still can, so I'm not too excited about it.

[babakfp]

I can't code when there are no JSDocs, also the current documentation is missing a lot of things.

[fzn0x]

I think we can start by focus on the implementation of TSDoc first, lets think about the Documentation matters later @yusukebe

I'm working on this now with AI 😄

[yusukebe]

@fzn0x You are great! I'm also thinking our next step is focussing JS/TSDoc. At first, what we can do is write middleware docs since we already have a good document of them on the website. For example, these have docs for options:

https://hono.dev/middleware/builtin/basic-auth

We have to just port it.

[yusukebe]

@fzn0x

I've created the draft PR for docs for all builtin middleware: #2680