excludeNotDocumented Won't Emit the Function Declaration

[capraynor]

Search terms

excludeNotDocumented d.ts function Declaration

Expected Behavior

The function declarations should be generated when excludeNotDocumented is true in the following cases:

• Methods inside classes
• Exported function in Module.

Actual Behavior

• Methods inside classes
• Exported function in Module.

The functions (call signatures) from above documents is not generated.

Steps to reproduce the bug

Step 1:
git clone https://github.com/capraynor/typedoc-method-declaration-not-extrated.git

Step 2:
run npm run build-api-doc

Regarding to this file:
https://github.com/capraynor/typedoc-method-declaration-not-extrated/blob/master/packages2/module1/index.d.ts

case1 is not generated (not good)
case2 is not generated (OK, because it is private one AND excludePrivate=true)
case3 is not generated (not good)

Please note that: excludeNotDocumented = true, the bug occurs. excludeNotDocumented=false, everything works fine.

Environment

• Typedoc version: 0.23.7
• TypeScript version: 4.7.4
• Node.js version: v16.15.1
• OS: Windows

Will share more information if we've found a clue.

Feel free to comment if you know which point should we check.

[capraynor]

Now this issue is Investigating by: @cary-hu

[Gerrit0]

Oops... how do I continuously forget about functions :/

This happens because functions don't have comments on their reflection, they instead have comments on their contained SignatureReflections

https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/plugins/CommentPlugin.ts line 403ish

[capraynor]

@Gerrit0

:/

Thanks for the reply.
Got it.

We are using d.ts.

Hence, the functions are Declaration.
Hence, the methods inside classes are Declaration

@cary-hu

When performing the fix, please don't forget about the .ts files. We should see if the comments inside methods and functions can be resolved correctly.

@Gerrit0

What we see - just to remind - I've found the following behavior, and we saw a related-solved-PR:

When excludeNotDocumented = true:

If The Object type declaration have comment, but the fields inside type declaration DO NOT have comment, the fields will be exported (expected behavior).

i.e.:

/ **
*
* Type A Description
*/
export type TypeA = {
   fieldA: string
}

The fieldA still can be exported.

This is by-design.

Related PR:
#1308

[cary-hu]

@Gerrit0 , we have try to fix this bug in #1997.
but I don't know how to add test case for that, could you please help us add some test case for this bug?

[capraynor]

@Gerrit0

but I don't know how to add test case for that, could you please help us add some test case for this bug?

Explanation:
We've found that in converter2, we have no chance to modify the typedoc option.
Since the bug need to be reproduced using excludeNotDocumented = true, could you please give more instructions to modify the option in UT?

Thanks.

[Gerrit0]

Copying from Discord for posterity:

Cary — 07/12/2022
actually, I added gh1994 method in issueTests.ts, But I don't know how to implement this method
I have checked other method in this file, But still have no idea with implement test method
Is there any user guide for implement test method?
Gerrit0 — 07/12/2022
For that one, you should just be able to query each function/method you expect to exist, I don't think more checks than that make sense
Cary — 07/12/2022
Because gh1994 is effected by excludeNotDocumented option, So I want update option before begin test, and restore the option after test, Do I truly need to do that
I'm not sure
and if should, how?
Gerrit0 — 07/12/2022
Restoring the option after the test runs is done automatically, you should be able to create a pregh1994(app) which does app.options.setValue("excludeNotDocumented", true) and then in gh1994(project) do query(project, "someFn") and query(project, "SomeCls.method"). query will throw if it can't find something, so that should be all that's necessary

[Gerrit0]

Fixed by #1997

[capraynor]

@Gerrit0
I will create test case later, busy on other issues these days.