Is using a documentation generation library an anti-pattern?

[lillallol]

Search terms

• publicApi.ts

Question

When I use a single file: publicApi.ts, that acts as documentation for my library, I get the following benefits:

1. no documentation generation library is needed
   1. no need to learn a new api
   2. less bloat for node_modules folder
   3. less security issues
2. the file can open in my favorite IDE, that means that anyone can read the documentation with:
   1. the theme they are used to
   2. the font they are used to
   3. the keyboard shortcuts they are used to
3. public api is easier to maintain when it is included in a single file rather than scattered in multiple files
4. I can define collapsible regions
5. I can put the most important stuff at the top of the file and the least important at the bottom
6. I can manually format it or use the formater I am used to
7. I can define types or inline them for the sole purpose of improving public api readability
8. JSDoc descriptions and types for the public API are gathered in a single place
9. there is no need to generate .d.ts files since publicApi.ts can be the entry point for types for my node module
10. there is no need for people to bundle .d.ts if they want to just use a bundled index.js, since they can rename publicApi.ts to index.d.ts

Given all these benefits why should anyone use any documentation generation library?

[hijarian]

If your whole API fits into a single file, then sure, you don't need an auto documentation library.

Such tools are for the projects on a completely different scale.

Also, you can't have hyperlinks in .ts file. And you probably want them for increased usability: links for external dependencies, inter-links between parts of your own documentation... To get hyperlinks, first, you would need to post-process the source code file somehow to make an HTML out of it. And suddenly, you're using a documentation generation library now. 🤷

[lillallol]

Also, you can't have hyperlinks in .ts file

.ts files can have JSDoc comments. Would that work for hyperlinks with a proper IDE support?

Such tools are for the projects on a completely different scale.

Can I see some real world examples.

I think a section should be added somewhere to inform people that they might not need typedoc. I think I had to re invent the wheel to understand that.

[Gerrit0]

Short answer:
No, it is not. It simply does not fit your use case.

Longer answer:
Documentation generation libraries like TypeDoc should never be assumed to replace complete declaration files for a library, or equivalent for other languages. That's explicitly not their job. The job of a documentation generator varies somewhat depending on the project using it, but here are a few which a header file does not meet.

1. Discoverability for non-expert users of a library. Declaration files are amazing. Personally, even though I maintain this thing, if a library I'm using has a published site, I will probably only use it for a couple days when getting started with the library to get a sense for what's available without having to read through the entire declaration file (tables of contents are good!). After that, and for very simple libraries, maybe even sooner, I'll default to the declaration file, switching to a browser only after failing to quickly find what I want via an editor.
2. Providing an alternative method for reviewing documentation, for users which prefer it. That's not you, generally not me, but I've worked with devs who genuinely prefer having a documentation website open on a second monitor to delving into the declaration files.
3. Meeting customer/management requirements for documentation (yes, really, it's dumb, but doxygen has saved me hundreds of hours in one job), having a documentation site can also make it easier to get libraries approved in locked down environments.
4. As an indication that the authors of a library have given more than a few minutes thought to how to make their library easy to use. There are a lot of packages on npm. If quickly reviewing half a dozen libraries which might serve a need, those which have a website, even with just a reasonable readme and a few pages on the available exports will be more closely reviewed as something I want to use. Libraries which tell users to go read the fine code... well, it'd better be very easy to quickly scan -- from a browser. I'm probably not even going to install something like that.

Many of the best libraries I've used don't use a documentation generator, but they tend to have manually written documentation as a replacement. Personally, I've found documentation generators existing to be useful because they result in devs writing more documentation, even if I never visit the generated site.

[lillallol]

tables of contents are good!.

We can get the top level identifiers of the .ts file which sort of acts like toc. This functionality is provided by default in VSCode. We can not get toc with nesting though for publicApi.ts, although user defined collapsible regions can aid in that.

switching to a browser only after failing to quickly find what I want via an editor.

The problem is that usually these declaration files have been automatically generated, hence not created with readability in mind, so people do not find them readable. ctrl+F in a single file that contains solely all the public api, instead of ctrl+shift+F multiple .d.ts files that contain public api mixed with private api, narrows down significantly the search scope, and makes it easier to find what you want.

devs who genuinely prefer having a documentation website open on a second monitor to delving into the declaration files.

I have hard time to understand these people. One of the things that I do not like about documentation generations libraries is that the documentation that gets produced is not familiar. I find it really hard to read documentation that does not open in IDE or github.

Libraries which tell users to go read the fine code... well, it'd better be very easy to quickly scan -- from a browser. I'm probably not even going to install something like that.

There is no need for install. In github we can open files like they were in VSCode. Just add .dev in the url instead of .com. Just add a link in README.md#documentation that points to publicApi.ts.

they result in devs writing more documentation, even if I never visit the generated site.

I have the opposite experience for my personal projects that use publicApi.ts. Deviating from publicApi.ts means no single source of truth for documentation, which means reduced DX for both the library consumer and maintainer. By the time I am writing documentation in a JSDoc comment that exists above a type,function,variable etc. , the "implicit context" is clearly defined, so that, there is no need to redefine it, and I can focus on what matters. When I write part of documentation in .md, I have to redefine the "implicit context" each time. Finally, refactoring and linting does not work in .md further reducing DX.

Also I have found myself wasting a lot of time to make the documentation generation libraries behave they way I want them. This time could easily be used to improve publicApi.ts.

---

Do you agree for a section to be added somewhere in typedoc documentation that informs people that they might not need any documentation generation library and instead use publicApi.ts. I am pretty sure that there are some people that are not aware of publicApi.ts and that they would use it instead of any documentation generation library. I was one of them for example.

In the end I feel publicApi.ts should be the default for documentation, and the usage of documentation generation library be something optional. I think like this the ecosystem will be way simpler than what it is now.

[drazisil]

Can someone share a link to info on this publicApi.ts? I'm not familiar with the concept.

[lillallol]

Well I can. Just tell me what you want me to do:

1. upload some of my unfinished projects so that you can take a look at their ./publicApi.ts, but likely not be able to execute the exported variables from the entry point
2. just post a publicApi.ts file here

[Gerrit0]

I don't feel that it's the job of a tool to tell people not to use that tool, unless that tool has become obsolete with further additions to the environment. Just because it doesn't make sense to you, the number of people who do want a documentation site indicates that there is still a demand for this.

[lillallol]

I don't feel that it's the job of a tool to tell people not to use that tool

I was thinking something along the lines of "you might not need redux" article created by the creator of redux. It will just inform people that they might not need typedoc.

the number of people who do want a documentation site indicates that there is still a demand for this.

There will always be demand for that. I am just saying that some (maybe most) of that demand is because people have not seen the alternative: publicApi.ts.

[Oblarg]

How do you maintain your publicApi.ts as your application scales? It sounds like you're describing the output of a tool like api-extractor, which is useful but not a replacement for a static docs site.

[lillallol]

How do you maintain your publicApi.ts as your application scales?

Can you be more specific. How is publicApi.ts going to get challenged when the application scales? If the file gets too big you can use collapsible regions.

not a replacement for a static docs site

What is the reasoning for that?

[Oblarg]

Single-file entry points eventually become unmanageable for actual browsing, collapsible sections or no. This is why tools like api-extractor come with built-in documentation generation plugins.

Finding that tooling doesn't make sense on the scale of a personal project and concluding that there's no reason for it to exist is a very elementary (and common) programming mistake.

[lillallol]

Single-file entry points eventually become unmanageable for actual browsing, collapsible sections or no.

Can I see a real world example where a documentation generation library made that manageable?

This is why tools like api-extractor come with built-in documentation generation plugins.

I do not understand what this has to do with our discussion?

Finding that tooling doesn't make sense on the scale of a personal project

Finding? You mean using?

[Oblarg]

Take a look at the documentation for a large-scale project like React.

[lillallol]

Is this what you are talking about?

[Oblarg]

No, I mean the API reference.

[lillallol]

That is not something big for ./publicApi.ts to become unmanageable. For such a project I would also have an ./examples folder.

I personally find it hard to read the documentation. Take for example useState. Here is what I would write in ./publicApi.ts for useState:

/**
 * @description
 * Hook to be called inside a component to define its state. 
 */
export declare const useState: <T>(
    /**
     * @description
     * If creating the context parameter on each render is cpu expensive, then 
     * provide a function that returns it, which will be called only in the 
     * first render and never again.
     */
    initialState : T | (() => T)
) => [
    currentState : T,
    /**
     * @description
     * Calling this, will trigger a re-render of the component, in which, the 
     * returned value of the context function, will be the state.
     */
    setNewState : (currentState : T) => T
];

Which one do you find more readable?

---

The ./README.md could have the following section:

## Documentation

Take a look at `./publicApi.ts`.

## Examples

Take a look at `./examples`.

In ./examples some examples about useState could be added.

By the way I am in the process of creating an MVC framework from scratch. It is when I went for ./publicApi.ts + ./examples that the projects public api documentation became manageable.

Look, although I lack the experience with creating/maintaining really big projects, we have to question whether an unmanageable ./publicApi.ts means that its time to split the project into more than one project (example).

Finally as far as I can see React is not using TypeScript. Maybe that is why I have hard time reading its documentation.

[adamscybot]

I've also mused on this and gone back and forth. One thing I would say is if you are using TypeDoc with something like Docusaurus (via the plugin), then it's nice to have your "guide" docs be able to link into the underlying API docs.

However, I think a lot of libraries just do the API docs and that's it, they don't have an overarching guide on how it all fits together, they just put the API docs online and leave it at that. I feel if you do that there's a higher chance the value is significantly lower as you've just created a reflection of what the IDE integration can provide. I don't blame them of course -- documentation is time-consuming. And I wouldn't say there's no value -- discoverability to newbies poking around deciding if to use your library is important. There's probably some SEO benefit as well in that end users who are googling an error from a black-box perspective might get them to the problem quicker.

The react example is interesting as it kind of smushes it into one, and ignores the nitty gritty verbosity of autogenerated API docs in favour of hand crafted wording. It's very nice in my opinion (some may disagree), but it's also a lot of work.

I've found a happy medium is some pages in docusaurus explaining the big picture but with links to specific places in the API docs.

[Dayday10]

How can this happen is it fixed?

…

On Sat, Aug 19, 2023, 10:18 AM Gerrit Birkeland ***@***.***> wrote: Closed #2310 <#2310> as completed. — Reply to this email directly, view it on GitHub <#2310 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AWMIKFIILMMMZ2ASRIBT6XLXWDKNJANCNFSM6AAAAAAZJTNIDQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>