How to force inclusion of non-exported variables?

[tomchen]

[Solved] Please use the typedoc-plugin-not-exported plugin to solve the problem described here.

npm i -D typedoc-plugin-not-exported

---

Search Terms

force include non exported unexported variable option flag tag mode file exclude

Problem

I can't find any way (either a @ tag in comment or an option / flag) to generate docs for variables that are not exported

Consider

(I don't export the type)

type twoNumbers = [number, number]
export function sum(ns: twoNumbers) {
  return ns[0] + ns[1]
}

or

(I only export the type used directly by the parameter)

type twoNumbers = [number, number]
type threeNumbers = [number, number, number]
export type twoOrThreeNumbers = twoNumbers | threeNumbers;
export function sum2(ns: twoOrThreeNumbers): number {
  return ns.reduce((a, b) => a + b)
}

or even

(I only export the instance of the class but not the class. Because user may use me.method(), I may want to include the methods of the class in my documentation)

class ClassName {
  ...
  method() { ... }
}
export const me = new ClassName()

It seems there used to be a mode: 'file' option, which has been removed in the latest version of typedoc, this option can enable inclusion of everything, including the non exported variables. (but I'm not asking for this option to be re-added, I just want a includeNonExported or similar option)

Suggested Solution

Something like a @includeindoc tag to force inclusion of a specific variable (preferably)
(I don't think @public can be used here, they are not public but I just want them to be included in the doc)

and/or

A global option / flag, that could be named includeNonExported or something, and allows to include all non exported variables.

[Gerrit0]

My knee-jerk reaction to this was "Why aren't you exporting your public API surface? That just makes it more annoying for anyone who uses it"

But, having slept on it now, I suppose there is some use for it... I think this can be a plugin, it isn't something I want to encourage. I should have time to at least briefly look into building one this weekend.

[tomchen]

These could be real-world examples:

Even in typedoc's API documentation (generated by typedoc), it is not hard to find non exported types / classes / variables that are not included in the documentation, but are potentially includable.

https://typedoc.org/api/classes/application.html

BaseTheme, AbstractComponent are not publicly exported therefore not included, so, [[]] cannot link to their non-existent pages, but, isn't that ugly to show [[]] in the description? Users could read the pages of Converter and Renderer that are subclasses of AbstractComponent, but I would not be surprised if someone insists on including BaseTheme and AbstractComponent (but tag them @ internal or something) for the the sake of completeness and in order to eliminate the ugly [[]].

https://typedoc.org/api/classes/application.html#listento

What are EventCallback and EventMap types / interfaces? Users could assume EventCallback is () => void but it's technically an assumption, a trial and error, it's not known for sure after reading the documentation. And EventMap is even harder to guess, users may have to explore the source code to understand it's { [name: string]: EventCallback } for sure.

[Gerrit0]

Yeah - TypeDoc could use this right now... but that's a failing on the part of TypeDoc, not an argument for this feature! TypeDoc has historically been really bad about exporting all the necessary classes/functions to create a plugin. It's something that's on my roadmap for 0.21 to fix. Once complete, there should be no (or very few) broken references in the docs.

[Gerrit0]

That wasn't very painful at all...

I'm not sure I want to maintain this, so here's the source. I disclaim any copyright to it. If you (or anyone) wants to publish it as a plugin, feel free.

typedoc src/index.ts --plugin path/to/plugin.js

This is somewhat limited - it can only know to include something in the documentation if TypeDoc documents a module which declares it... I think that should be good enough for most use cases. If it isn't in scope, then there's not really a good way to go find it.

Plugin source

//@ts-check

const { Converter, TypeScript } = require("typedoc"); // version 0.20.x

const ModuleFlags =
  TypeScript.SymbolFlags.ValueModule | TypeScript.SymbolFlags.NamespaceModule;

/** @param {{ application: import("typedoc").Application }} param0 */
exports.load = function ({ application }) {
  let includeTag = "fakeExport";

  application.options.addDeclaration({
    name: "includeTag",
    help:
      "[typedoc-plugin-not-exported] Specify the tag name for non-exported member to be imported under",
    defaultValue: includeTag,
  });

  application.converter.on(Converter.EVENT_BEGIN, () => {
    includeTag = application.options.getValue("includeTag").toLocaleLowerCase();
  });

  application.converter.on(
    Converter.EVENT_CREATE_DECLARATION,
    lookForFakeExports
  );

  /**
   * @param {import("typedoc/dist/lib/converter/context").Context} context
   * @param {import("typedoc").DeclarationReflection} _reflection
   * @param {TypeScript.Node | undefined} node
   */
  function lookForFakeExports(context, _reflection, node) {
    if (!node) {
      return;
    }

    /** @type {TypeScript.Symbol | undefined} */
    const moduleSymbol =
      context.checker.getSymbolAtLocation(node) ??
      /** @type {any} */ (node).symbol;

    if (!moduleSymbol) {
      // Global file, no point in doing anything here. TypeDoc will already
      // include everything declared in this file.
      return;
    }

    // Make sure we are allowed to call getExportsOfModule
    if ((moduleSymbol.flags & ModuleFlags) === 0) {
      return;
    }

    const exportedSymbols = context.checker.getExportsOfModule(moduleSymbol);

    const symbols = context.checker
      .getSymbolsInScope(node, TypeScript.SymbolFlags.ModuleMember)
      .filter((symbol) => !exportedSymbols.includes(symbol));

    for (const symbol of symbols) {
      if (
        symbol
          .getJsDocTags()
          .some((tag) => tag.name.toLocaleLowerCase() === includeTag)
      ) {
        context.converter.convertSymbol(context, symbol);
      }
    }
  }
};

[tomchen]

Thanks.

Yeah sure https://github.com/tomchen/typedoc-plugin-not-exported npm i -D typedoc-plugin-not-exported

[lillallol]

@Gerrit0

I think this can be a plugin, it isn't something I want to encourage

That is because, it is a bad practice for someone to not export from the entry point all the types needed for documenting the concretions exported from the entry point?

[Gerrit0]

I would argue yes - all the types that a library user might need for working with the library should be exported. There are probably some people who will disagree with me on this, but my response is that if it's already exported implicitly, you might as well export it explicitly and make your user's lives easier.

export declare class Foo {
  method(x: SomeNotExporterType): void
}

// If I need this type, I have to do:
type LibIsBad = Parameters<import("lib").Foo["method"]>[0]

[lillallol]

@Gerrit0
So lets say I make a node module that uses puppeteer. The exported concretions from the entry point use some types from the puppeteer library in their type signature, like Browser and Page . In that case should I export also the puppeteer types from the entry point of my node module?

[Gerrit0]

As a user of your lib, I would say yes please! Exporting them from your lib means:

1. I get autocomplete when importing them (TypeScript doesn't look at non-direct dependencies for auto import*)
2. I can be sure that I'm using the same version of types as your lib.

TypeDoc does this for TypeScript - even though it's a peerDependency, but to keep the size of the docs manageable, we have excludeExternals turned on.

https://github.com/TypeStrong/typedoc/blob/b2a88ba47d2d24f1ca5b47d02883a3bf182af2c4/src/index.ts#L41-42

* this might not necessarily apply if the dependency's types live in an @types package... the rules there have changed a few times, I'm not sure what the current one is.

[mnn]

I would add an example where in my opinion it's the correct approach to not export classes. I maintain a small library - ts-opt. Roughly it is a nicer | undefined/| null.

A user is expected to never directly create an instance via new nor use type Some and None.

In case of instantiation, a user is supposed to use opt function (and its variants), sometimes none value, rarely some (it may lead to logical errors when dealing with half-typed code, e.g. using lodash).

If a user ever references the type directly - Some/None - then it means a user misunderstood how the library works and it is considered an error. Because when you use Some<T>, you should just use T directly (it means you know you have a "filled" Opt, so there is no point in passing it wrapped only to unwrap it as soon as you work with the T). If you use None<T> then it's even worse, because only equivalents are one-value types like null, undefined or similar, so it's useless to have a such type, because regardless where it's used, it means it has to be there, but can only ever be (carry) one value which is equal to not having it (field or argument) there at all. (How often do you see for example an argument of a function of type null - (a: null) => number? Or a field in an object of type undefined - {id: undefined, name: string}? It's very rare, usually a mistake.)