Typedoc: feat: Add support for documentation on nested optional object/interface

[diosney]

• [x] I have checked issues with enhancement label and found no duplicates

Problem

I've the following interface definition with documentation comments:

export interface IPaymentUrls {
  /** Some description. */
  redirect?: {
    /** Some other description. */
    success: string;

    /** Another description?! */
    cancellation: string;
  }
}

Sadly, in the docs it outputs the redirect variable as optional, which is fine, but then omits all the other nested properties from the documentation, like if they never existed.

Suggested Solution

Even if the properties are optional, if they have comments or types, and even if they have an any type, they should be shown in the docs.

[Gerrit0]

Question: If you turn off excludeNotExported, does the reflection show up? #901 seems to indicate that this is a bug.

[9oelM]

This issue needs proper reproduction (with excludeNotExported). Perhaps I will have a look some time later when I have some time.

[diosney]

@Gerrit0 Sorry but even with that flag turned to false they do not show up.

My object is the following:

export interface IPaymentUrls {
  /** URLs related to the buyer redirection after some specific events in the Payment Web App flow. */
  redirect?: {
    /** URL that the Merchant can set and that the Payment Web App will use to redirect the buyer when it *successfully completed* the payment. */
    success?: string;

    /** URL that the Merchant can set and that the Payment Web App will use to redirect the buyer when it *cancels* the payment. */
    cancellation: string;

    /** URL that the Merchant can set and that the Payment Web App will use to redirect the buyer when there is an error with the payment. */
    error: string;
  }
}

When redirect is optional, the documentation shows up like the following (with the frag or without it):

https://imgur.com/L9thSTo

And removing the optional attribute to redirect correctly outputs the following:

https://imgur.com/4DRiKu1

(I set success to optional to further test them)

If I have another nested object, only if it is not optional gets added to the documentation, also, the same behavior applies.

[Gerrit0]

Thanks for the reproduction! This is clearly a bug.

[alalonde]

I tested this with and without the --excludeNotExported flag. The nested members do show up when the flag is omitted.

[Gerrit0]

This has been fixed + released in v0.16.0

[grit96]

I can still reproduce this on typedoc v0.19.1.

With optional:

Without optional:

I used this command to run typedoc:

$ npx typedoc client/common/hooks/useTable.ts

$ npx typedoc --version

TypeDoc 0.19.1