Replacement to TSDoc for API documentation

[goisaki]

As proposed by @yusukebe, TSDoc is a sufficient replacement for our API documents. I believe this change will enhance the simplicity and maintainability of the project.
In this discussion, I would like to talk about opinions on this change, potential issues, and possible solutions.

I'd especially love to hear from:

• @yusukebe
• @usualoma
• @MathurAditya724
• @NicoPlyley
• @ryuapp

[6km]

TSDoc is good.

[yusukebe]

Related to #1338

[NicoPlyley]

Would we be removing the API from the docs altogether? It is a great reference guide, if I forget a name for something or want to link to someone on how to use a certain feature.

TSDoc also does not work for me in WebStorm or anyone using other editors. I have to jump to the source to read it, unlike VS Code where I can hover over a function to see the information. Am I missing something here? It seems like we'd be getting rid of a lot of useful information on the website.

[yusukebe]

Hi @NicoPlyley !

What I'd like to do is "JSDoc First." We won't create both JSDoc and the website together, but we'll have both.

I'm thinking of creating the public documentation for the website from TSDoc/JSDoc. For example, TypeDoc seems to be good for us. We may generate the Markdown for VitePress from TSDoc/JSDoc in the source codes. This was discussed in #1338.

The following is my example of generating the TypeDoc from the source code (it's not integrated with VitePress). Looks good:

Unifying the format, styles, directory structure, URL path, etc., will be difficult, but this is not a bad solution. Ideally, the generated documents would be accessed from https://hono.dev/api or https://hono.dev/docs/api.

[6km]

https://hono.dev/api or https://hono.dev/docs/api

@yusukebe I guess https://hono.dev/api is better, it should be separate from the docs as it will have more technical details instead of just code samples and guides.

[goisaki]

https://hono.dev/api or https://hono.dev/docs/api

@yusukebe I guess https://hono.dev/api is better, it should be separate from the docs as it will have more technical details instead of just code samples and guides.

Already discussed.

[6km]

Oh. I didn't notice that.

[NicoPlyley]

Thank you for clarifying this @yusukebe this makes a lot more sense and would appear to save time in the future, as long as the generated docs are still simple. I think a wonderful thing now about the API docs is how simple they are to go over everything.

[yusukebe]

WIP

Google.Chrome.mp4

I think this is super cool! I would like to ask for help from all of you, so please wait a little longer until I am ready to do so.

also cc: @fzn0x

[fzn0x]

Cool!!

[yusukebe]

Hi @goisaki @NicoPlyley @6km

I am trying to generate all documentation for APIs from the source code JSDoc on this matter (JSDoc First). But I'm beginning to realize that is very hard to do for several reasons. I will struggle a bit more, but maybe I will change our approach. So please be patient. I will get back to you.

[6km]

@yusukebe I have made a demo using Typedoc a week ago but I'm not sure if it's 100% done, and it has the same style as the docs of Hono.
By the way, Typedoc uses the @module tag to determine the name of the page that the code will be documented in. If not provided, it will detect its name and group it under the directory it belongs to as example

• helpers
  • css
  • dev
  • accepts
  • factory
  • ...

[yusukebe]

Hey! By the way, can you share your favorite document website for software? e.g. Bun, Valibot

[fzn0x]

https://vitest.dev/api/ vitest is cool

[goisaki]

I like Valtio.
Incredible, but it is made in Next.js, not Docusaurus, Vitepress, etc.

[yusukebe]

Thank! I want to know how to structure and word the website well. So, it does not depend on the tools!

[yusukebe]

Hi. Especially @goisaki @6km @NicoPlyley @fzn0x

I proposed generating API documentation from JSDoc/TSDoc, but I'm sorry, I would like to stop this proposal. This is the conclusion of my consideration and prototyping. The reasons are below:

• The generated document is boring. We need to write enough descriptions.
• It's hard or impossible to write everything in the code. There will be more lines in the code that are not related to the implementation.
• Contributing will be difficult. With the current website, you can just edit the markdown, but with JSDoc, you have to change the code.
• Documentation generation is difficult. The flow of code to document and web page generation is complicated.

Sorry for suggesting it.

However, JSDoc is good for having descriptions in the IDE. Try to write minimum parameters and examples.

The next step for documents, let's continue the following.
honojs/website#357

Thanks!