Typedoc: Improve Internal/External code distinction

[aciccarello]

There is a lot of confusion on the Internal/External code distinction. Ideally, internal code would include the types in the project while external code would be libraries. TypeDoc currently uses the input files as the distinction between these two which is insufficient in cases where users want to use an entry file as their input.

• [ ] Change default to mark files in a node_modules or libs directory as external rather than input files
• [ ] Document how to use --externalPattern for more granular control
• [ ] Rename "Externals" to "Libs"

Related issues: #124, #673

[diosney]

Besides renaming "Externals" to "Libs" it could be awesome if there was a way to differentiate code to be consumed internally from the public exported API, something like typedoc-plugin-internal-external tries to do at the Aliases section, but that is so counterintuitive (besides misusing the External/Libs feature for that).

Maybe after "Libs" gets added, "Externals" can be repurposed to differentiate between Internal APIs from the External exported public surface?

Hope you understand what I mean.

[aciccarello]

@diosney That's a good point. So you are thinking there should be a Libs, Public, and Internal distinction?

[diosney]

@aciccarello Yes, that was what I meant! Do you think that is possible? It could be really awesome :D

[aciccarello]

@diosney Great, splitting internal into public and internal should be something we can look at when implementing #639

[DanielSchaffer]

If we're talking internal, this is probably worth at least keeping an eye on: https://github.com/Microsoft/TypeScript/issues/5228

[tobiasschweizer]

I am experiencing the issue that most of my code gets flagged as isExternal: true when I look at the JSON representation (using --json option).

I think this is because of the way this method is implemented:

https://github.com/TypeStrong/typedoc/blob/3f6395671f07d70c2e508d2b1b34d626d86bfea1/src/lib/converter/context.ts#L403-L415

If I am not mistaken, this.fileNames contains the files that are set up in tsconfig.json:

https://github.com/TypeStrong/typedoc/blob/3f6395671f07d70c2e508d2b1b34d626d86bfea1/src/lib/converter/context.ts#L25-L28

So my tsconfig.json looks something like this:

  "files": [
    "index.ts",
  ],
  "include": [
    "src/**/*.ts"
  ]

Does this mean that the whole directory src is flagged as external because only files is used to check if something is external?

Could there be something like an internalPattern?

Edit: I have just noticed that it was probably my fault: I used typedoc src/*.ts which just included the files that were directly in src. Changing it to src works.

Then I get all the files in fileNames: https://github.com/TypeStrong/typedoc/blob/3f6395671f07d70c2e508d2b1b34d626d86bfea1/src/lib/converter/converter.ts#L276

[Gerrit0]

The external distinction has changed significantly in 0.20.... along with a ton of other stuff. Symbols (not files) are now marked external based solely on externalPattern, and TypeDoc defaults to marking symbols as external iff they come from node_modules. I'd recommend taking a look at typedoc@beta, which probably gives output closer to what you want by default. typedoc src/index.ts should be all that's necessary.