Exclude externals do not seem to work in 0.24.0

[akphi]

Search terms

exclude, externals, packages strategy

Expected Behavior

External packages should not be scanned when excluded with externalPattern and excludeExternals combination

Actual Behavior

External packages are still scanned and warnings are shown

Steps to reproduce the bug

Follow the steps in Gerrit0/typedoc-packages-example#1

Environment

• Typedoc version: 024.0
• TypeScript version: 5.0.4
• Node.js version: 16.8.0
• OS: MacOS 13.3 (22E252)

[Gerrit0]

This is (mostly) working as expected. You set the excludeExternals option in the root project, but those options only apply when doing the project merge. I experimented with automatically inheriting option values when converting each package, but it unfortunately ended up being confusing regarding which options were set, so I decided not to do so.

I should probably update that example to use a base typedoc.json that packages extend, since that's what most monorepos will probably want to use.

With these changes, the lodash functions are no longer included in your documentation, and you will no longer receive warnings about their comments.

diff --git a/packages/foo/package.json b/packages/foo/package.json
index 5041dbb..3d88be5 100644
--- a/packages/foo/package.json
+++ b/packages/foo/package.json
@@ -11,6 +11,10 @@
   "typedocOptions": {
     "entryPoints": [
       "src/index.ts"
-    ]
+    ],
+    "externalPattern": [
+      "**/node_modules/**"
+    ],
+    "excludeExternals": true
   }
 }

I say mostly working as intended, because this @example block should really fall under TypeDoc's jsDocCompatibility option and be detected as not containing a code block. Currently, TypeDoc is picking up on `_.property` and deciding that the block includes code, and therefore should not be automatically treated as code. I think it makes sense to adjust this check to not just check for any code spans, but a code block (starting with ```)

    interface LoDashStatic {
        /**
         * This method is like `_.uniq` except that it accepts `iteratee` which is
         * invoked for each element in `array` to generate the criterion by which
         * uniqueness is computed. The iteratee is invoked with one argument: (value).
         *
         * @category Array
         * @param array The array to inspect.
         * @param [iteratee=_.identity] The iteratee invoked per element.
         * @returns Returns the new duplicate free array.
         * @example
         *
         * _.uniqBy([2.1, 1.2, 2.3], Math.floor);
         * // => [2.1, 1.2]
         *
         * // using the `_.property` iteratee shorthand
         * _.uniqBy([{ 'x': 1 }, { 'x': 2 }, { 'x': 1 }], 'x');
         * // => [{ 'x': 1 }, { 'x': 2 }]
         */
        uniqBy<T>(array: List<T> | null | undefined, iteratee: ValueIteratee<T>): T[];
    }

[akphi]

This is (mostly) working as expected. You set the excludeExternals option in the root project, but those options only apply when doing the project merge. I experimented with automatically inheriting option values when converting each package, but it unfortunately ended up being confusing regarding which options were set, so I decided not to do so.

Would be great if we could update the doc to indicate which configs/options are inheritable for strategy=packages

I should probably update that example to use a base typedoc.json that packages extend, since that's what most monorepos will probably want to use.

I took a wild guess and tried to do something like

/packages/foo/package.json
   "typedocOptions": {
     "extends": ["../../typedoc.shared.json"],
     "entryPoints": [
       "src/index.ts"
    ]
 }

didn't work though 😅 so if we could have example/doc that would be super great. Thank you so much!!

[Gerrit0]

PR welcome for the docs! I'll get something up there eventually, but it'll probably be next weekend, busy with family tomorrow :)

The "extends" key is only valid within the --options file. I've updated the packages example to use options files instead.