docs: Add JSDoc for all events

[Zearin]

The official JSDoc events is confusing and poorly documented, so this is really just “tagging” where event are listened for, and where they are emitted.

…That said, I think it’s a good start towards documenting the public API of Eleventy’s internals. JSDocs like this—even when they exist only in the source—will be particularly helpful for plugin authors who want to explore what they are able to do, and how they might do it.

[zachleat]

What does this add, practically? More documentation in an eventual generated JSDoc website?

[panoply]

I've touched on this in #3296.

As of now, unless the roadmap specifies otherwise, Typings should be utilizing a standardized defineConfig approach. Given the current architecture, full-featured type support without relying on JSDocs is best achieved by passing a function to module.exports (or as of ESM export default). This tactic is somewhat a necessity because the default export is a class:

const Eleventy = require("@11ty/eleventy");

// Create an instance
const eleventy = new Eleventy();

Developers using the default class export (i.e., programmatic control) can benefit from JSDocs defined types or alternatively by pulling in a specific @types module via DefinitelyTyped. However, this solution does not address the needs of developers using the .eleventy.js configuration file. The majority likely fall into this latter category, based on the plugin ecosystem and the streamlined control it offers. The .eleventy.js configuration file expects a function, making type assertions without comment annotations not possible:

module.exports = function(eleventyConfig) {}

Currently, developers leveraging JSDoc annotations need to use the following approach:

/**
 * @type {import('@11ty/eleventy')}
 */
module.exports = function(eleventyConfig) {}

This method is cumbersome and not necessarily intuitive for several reasons:

1. Many developers are unaware that the TypeScript Language Server supports type checking and completions using JSDoc annotations, so they might not think to use it.
2. The existing typed methods are mostly incomplete and exist within the core of the codebase, making upkeep difficult and requiring source code augmentation for changes.
3. The current approach and related discussions rely on JSDoc typings for completions and checks. Despite the capabilities of the TS Language Server and compiler, generating a virtual declaration for these completions remains necessary.

[Zearin]

What does this add, practically? More documentation in an eventual generated JSDoc website?

@zachleat That was my plan, yeah.

I was hoping to eventually steer this (and other JSDoc work) into a types file that can be used for autocompletion.

---

As of now, unless the roadmap specifies otherwise, Typings should be utilizing a standardized defineConfig approach.

@panoply Can you explain to me what that means?

Most of all, I have been trying to get documentation PRs merged for some time. To make it easier, I have been trying to submit smaller JSDoc PRs like this one, focused on a particular topic or part of the codebase.

I don’t particularly enjoy reading or writing TypeScript, but I love the autocompletion it offers in editors, which is why I was hoping to go with the “typings generated from JSDocs” approach I mentioned above to @zachleat.

1. Many developers are unaware that the TypeScript Language Server supports type checking and completions using JSDoc annotations, so they might not think to use it.

I’m not so sure about this one. There has been lots of discussion about JSDoc’s ability to work with the TS Language Server for years. Check out:

• this 2021 article
  • analysis & reaction video
• this article by DHH (whom I don’t always agree with; I mention because he has a large following, showing this idea has had plenty of time to reach a widespread audience)
  • analysis & reaction video

2. The existing typed methods are mostly incomplete and exist within the core of the codebase, making upkeep difficult and requiring source code augmentation for changes.

I’ve been happy to dive in and document the changes. (Unless, of course, I am taking on a fool’s errand. … …Am I?)

The most important parts of a JSDoc—as far as I know—are an overall brief descriptive summary, and the types and descriptions of params (and return types). These live directly below the JSDoc. I don’t think it’s any more difficult to document in JSDoc than it is to rewrite everything in TypeScript.

I do agree the chance for divergence is greater if you try to document everything in greater detail than what I’ve been attempting. I was hoping to work towards a minimalist-but-useful amount of annotation.

3. The current approach and related discussions rely on JSDoc typings for completions and checks. Despite the capabilities of the TS Language Server and compiler, generating a virtual declaration for these completions remains necessary.

Yeah, I was toying with generating this stuff, too. I was just trying to keep my PRs as small an easy-to-review as I could. Maybe I’ve failed… 🤕

Anyway, @panoply: Where (or how) do you think my efforts be most likely to be accepted?

[panoply]

Hey @Zearin,

See #3296 and specifically the defineConfig tactic. JSDoc annotations are covered with plugin support applied, along with documentation references in descriptives.

[Zearin]

@panoply Okay! So, what I got from the referenced issue with defineConfig is that end users just wrap their eleventy.config.js exported function in defineConfig, and that should provide autocompletion to the end-user.

Do I have that correct?

[panoply]

@Zearin, I apologize for not providing a more thorough response in previous comments. I had a busy weekend.

To elaborate: using defineConfig is a syntactic sugar that allows for isolated type support without needing JSDoc annotations directly in the project source. The linked issue (#3296) references 11ty.ts, which covers approximately 80-90% of the API. While DefinitelyTyped would be ideal, this approach requires an export function callback, hence its existence as an NPM module.

You mentioned:

Good start towards documenting the public API

Using JSDoc annotations has limitations, particularly in auto-typing plugins that expose declarations. For example, this section demonstrates how it’s currently possible with 11ty.ts.

From what I understand, this PR aims to provide better references of internal events and additional methods in the Eleventy API so as to improve end-user understanding. The changes include various annotations, some of which are available in 11ty.ts, such as:

• Events: L18-L28 and L793-L812
• Server: L222-L291

While the event API is not fully covered yet, end-users can reference and leverage IntelliSense for plugins or existing methods provided by the eleventyConfig parameter. Extending this to support instances (e.g., new Eleventy()) would be straightforward.

FWIW: I wanted to chime in on this PR, aside from the needs-discussion tag, because it relates to issue #3296 and focusing on public-facing references. I am also interested in this topic and been wanting to see some action or better discussion, but given a lot of 11ty users are JS purists, it seems a bit hard to move the needle.

In previous discussions on these topics, the general consensus has been to expose typings via JSDoc annotations. While this approach works and can provide IntelliSense (auto-completion) support for developers, I believe JSDoc annotations are more suited for internal use within projects rather than for external usage for project consumers. However, I do understand their value proposition in this context.