Nested parameter descriptions

[zone117x]

• I have checked issues with bug label and found no duplicates

Expected Behavior

Based on a previous issue #497 (comment) it appears that nested parameter definitions are supposed to be generated in the html output.

For example, using the same code from that issue:

/**
 * Test method with object param
 * @param options Describing the options param
 * @param options.first A description of the first property of the options param
 */
public foo(options: { first: string, second: number, third: (a: number) => number })..

Is supposed to generate a list of the options parameters like the referenced screenshot:

Actual Behavior

When I try this same code or anything like it, it never shows the object properties / nested parameters, only object.
Screenshot:

Steps to reproduce the bug

Using command:

typedoc --tsconfig tsconfig-typedoc.json --out docs src

With tsconfig-typedoc.json:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "declaration": true,
    "noImplicitAny": false,
    "outDir": "lib",
    "sourceMap": true
  },
  "include": [
    "src",
  ],
  "typedocOptions": {
    "readme": "src/auth/README.md",
    "mode": "file",
    "excludePrivate": true,
    "excludeProtected": true,
    "excludeExternals": true,
    "excludeNotExported": true,
    "includeDeclarations": false,
    "target": "ES6",
    "gitRevision": "master",
    "listInvalidSymbolLinks": true
  }
}

Example code:

export class FooBar {
  /**
   * Test method with object param
   * @param options Describing the options param
   * @param options.first A description of the first property of the options param
   */
  public foo(options: { first: string, second: number, third: (a: number) => number }) {
    console.log(options)
  }
}

Environment

• Typedoc version: 0.14.2
• Node.js version: 10.15.3
• OS: macOS 10.14.3

[fc]

@zone117x It looks like the issue you are describing is possibly due to or related to the excludeNotExported option being set to true since I ran into a similar problem. See here for something more in-depth #1000 . You may have luck setting that to false and see what gets generated then?

[maoueh]

@Towerism Tried with excludeNotExported: false and same behavior.

[maoueh]

I produce a really minimal repro cas here, from my findings, strict: false vs strict: true causes the problem on my repro case: https://github.com/maoueh/typedoc-bug-987-repro

git clone https://github.com/maoueh/typedoc-bug-987-repro.git
cd typedoc-bug-987-repro
yarn install
yarn run typedoc --module commonjs --out docs
grep "NestedParameter" ./docs/modules/_index_.html

Should print `NestedParameter results but founds nothing.

Change in tsconfig.json to strict: false (or rm tsconfig.json) and then check again.

[maoueh]

Other files (for easier reference):

// index.ts
/**
 * @param options RootParameter
 * @param options.under NestedParameter
 */
export function under(options?: {under: boolean}) {}

// tsconfig.json
{
  "compilerOptions": {
    // Offending option!
    "strict": true,
  }
}

// package.json
{
  "name": "typedoc-bug-987-repro",
  "version": "1.0.0",
  "license": "MIT",
  "devDependencies": {
    "typedoc": "^0.14.2",
    "typescript": "^3.1.3"
  },
  "dependencies": {}
}

[fc]

@maoueh you might find it useful to include the output and diff of --json output.json for when strict is either true/false. It gives a more clear picture of what the underlying parser sees. That's what helped me when going down the rabbit hole of uncovering the bug I posted in #1000.

[maoueh]

Perfect, I'll do. I just tried the strict: false on my full project (https://github.com/dfuse-io/client-js) and the nested parameters are still not rendered.

I'll do what you suggested for the smaller repro. One step at a time I guess :0

[maoueh]

Ok, your suggestions was enlightening. The bug appears when the parameter that we want nested is an union which simple appears to not be the case when strict: false. The issue I'm reporting here seems different than original poster that do not have anything like that (unless it also become a union somehow?!?)

With strict: true:

"type": "union",
"types": [
    {
        "type": "intrinsic",
        "name": "undefined"
    },
    {
        "type": "reflection",
        "declaration": {

With strict false:

"type": "reflection",
"declaration": {

A more easily repro case not involving strict: false would be:

/**
 * @param options RootParameter
 * @param options.under NestedParameter
 */
export function under(options: {under: boolean} | undefined) {}

Would you accept a PR that allow nested parameters to appear if an union type? I would restrict it to union leading to undefined or null only (... | null, ... | undefined, ... | null | undefined) to start.

[maoueh]

I confirm is a complete different bug :$

When trying OP example, it's possible to make it work as expected by removing excludeNotExported like you suggested. I'll fill a new bug report.

[maoueh]

For future reference, new bug issue is #1020

[Gerrit0]

This has been fixed in 0.16. The code in the report now renders as: