Warning states Object is defined and referenced, but not included in the documentation. Why?

[KyleTryon]

I am receiving quite a few warnings of the same type describing that a component of my code is defined, and referenced within the code, but has not been included in the docs. I am not finding, however, why this is or what I am meant to do to resolve it.

Example of Error:

MyClassSchema, defined at src/lib/MyClass.ts:24, is referenced by MyClass.generate.generate but not included in the documentation

Notice here generate is written twice, I found this strange.

Here is the Interface that is being defined here:

/**
 * JSON Schema for the Persist command.
 */
export interface MyClassSchema extends CommandSchema {
  my_class: MyParameters;
}

And here is how it was referenced:

export class MyClass extends Command {
  parameters: MyClassParameters;
  constructor(parameters: MyClasstParameters) {
    super('my_class');
    this.parameters = parameters;
  }
  generate(): MyClassSchema {
    ...
  }
}

Now possibly why, and worthy of note, is that MyClass here is overwriting the definition of generate() which was defined in Command, this may be why we see generate twice, and possibly why it is not being exported? If that is the case, this may be a bug?

However, counter example to the immediate above comment: I am also experiencing this in an interface that is being used as a struct on a class.

export class X implements IntefaceY {
  ...
}
export interface InterfaceY {
  ...
}

This too is getting this error:

Warning: IntefaceY, defined at src/lib/X.ts:121, is referenced by X but not included in the documentation.

[timohausmann]

I also get this error a lot and don't understand why. My minimal reproducible example:

// types.d.ts
export interface TestInterface {
    x: number
}

// index.ts
import { TestInterface } from "./types";

export function test(props: TestInterface) {
    console.log(props);
}

$ npx typedoc index.ts
Warning: TestInterface, defined at types.d.ts:0, is referenced by test.test.props but not included in the documentation.

With npx typedoc types.d.ts index.ts the warning disappears, but then each file appears as a single module in the docs (undesired). And I don't think I should list every ts file in the command.

[krisztianb]

Sounds like the expected behaviour and you are looking for this: https://github.com/Gerrit0/typedoc-plugin-missing-exports

[timohausmann]

Aha, so by default only exports from the direct entrypoints are included, this clarifies things. Thank you.

[Gerrit0]

Yep, this is expected behavior. Users of your library will (unless you tell them otherwise) import lib not lib/some/internal/path, so TypeDoc warns that you aren't exporting the necessary types from what you designated as the entry point.

Notice here generate is written twice, I found this strange.

This is an artifact of getFullName, which just walks up the reflection tree to the project root. generate has two members in that tree - one for the signature, and one for the member itself. It works this way so that overloads can be represented... A PR which changes that for reporting here would be accepted :)

[srmagura]

Hmm, I just started getting this warning in my library too, but my case is more complex than the minimal repro by @timohausmann. I am curious if you all still think TypeDoc is correct to print a warning.

This is in a monorepo that contains packages iti-react and iti-react-core. Here is an abbreviated version of my code.

iti-react-core/src/Validation/Validators.ts (source code)

import { Validator } from './Validator'

function email(): Validator<string> {
    return /* ... */
}

export const Validators = {
    email
}

iti-react-core/dist/Validation/Validators.d.ts (declaration file generated by TypeScript)

import { Validator } from './Validator'

declare function email(): Validator<string>

export declare const Validators: {
    email: typeof email
}
export {}

iti-react/src/index.ts (source code — iti-react exports everything contained in iti-react-core)

export * from '@interface-technologies/iti-react-core'

And the warning from TypeDoc:

Warning: email, defined at iti-react-core/dist/Validation/Validators.d.ts:12, is referenced by @interface-technologies/iti-react.Validators.__type.email but not included in the documentation.

There are no warnings if I run TypeDoc on only iti-react-core. It really is the declaration file that is causing the warning.

[srmagura]

Hmmm, I finally took a look at the generated documentation like I should have in the first place. TypeDoc is right, email really isn't in the documentation:

I can't tell if TypeDoc is handling this situation in a suboptimal way or if I just need to refactor my code for it to work correctly with TypeDoc.

[Gerrit0]

Looking at the declaration file - I'd say... yes, for how TypeDoc works today, it is correct to produce a warning here. It could certainly be argued that TypeDoc isn't handling "variable namespaces" optimally here, and should have a special case for this, though (should probably be a new issue, that lays out when variables should be treated as namespaces, and when they shouldn't)

[y-polonsk]

It seems though if I don't want to include certain types in the documentation, e.g. by using tags hidden or internal (with excludeInternal option set), I still get the same warning if these types are used in definition of other publicly visible types. Is there a workaround for this?

[Gerrit0]

https://typedoc.org/options/validation/#intentionallynotexported, could also turn that validation off with --validation.notExported false

[y-polonsk]

Thanks, it works.