It's not clear how to run this on TypeScript files (f.e. it produces empty docs)

[trusktr]

Gleening from some examples in the issues, I'm running

documentation serve ./src/index.js --parse-extension ts

and src/index.js has an export * from './components' where the ./components folder has index.ts, and I get

Error: Cannot find module './components' from '/Users/trusktr/src/infamous+infamous/src'

Then I tried

documentation serve ./src/index.js --parse-extension ts --require-extension=.ts

and that got me to

Error: Cannot combine flow and typescript plugins.

It'd be sweet if the documentation has all the deets on running this on TypeScript. The word "typescript" doesn't seem to be found anywhere in the docs.

[trusktr]

@devongovett I see you made the PR. Would you mind explaining it a bit?

[devongovett]

I contributed TS parsing support. I have not used it with the built in documentation CLI though. I've been using it with gatsby.

[trusktr]

Does that mean you're using it with the Node API? It would be helpful to know how to use that too.

[devongovett]

I'm using gatsby-transformer-documentationjs.

Looks like that just calls documentation.build: https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-transformer-documentationjs/src/gatsby-node.js#L198

[trusktr]

Hmm, and with no options other than shallow. I guess that doesn't help to know why the CLI fails.

[rdmurphy]

This seems related to my #1269 — I think you cannot currently cross back and forth between JS/TS. My hunch is because the input is a .js file, it opts out of any TypeScript parsing and commits to activating Flow.

[trusktr]

Is there any way to tell documentation.js to ignore any source code, and only take whatever I've written in jsdoc-like comments to be the source of all truth?

For example, suppose I stick the jsdoc-like comments in a .cpp or .java file: can I get it to ignore the source, and just generate docs from the comments?

[tmcw]

From 2015-2016 it did! As 'polyglot' mode, which was removed in the 5.x because it was rarely used and was adding overhead to all the code paths downstream.

[trusktr]

With all the current options available (including even typedoc), I'm finding it to be a hard time documenting TypeScript code due to various issues (either tools choke on TS syntax, or they try to infer too much). It seems like a "polyglot" mode is the only way to let me have full control in my comments (without syntax or inference getting in the way). Maybe I should try 4.x...

[trusktr]

I tried ensuring that all files are .ts files, and now when I run documentation build ./path/to/src/index.ts, it outputs:

[]

Seems as though it doesn't see any documentation.

[tmcw]

I'll try giving this a look. The JavaScript ecosystem is… chaotic. Thanks to Webpack, lots of folks started abusing import & require statements to load images, css, text, markdown, and other… stuff… in bizarre ways. What import means kind of melted away into the solvent of configurability, and documentation.js has tried to support 'all the ways', which is a little sisyphysian.

Extracting JSDoc comments from cpp was something I wrote because we were documenting cpp node addons, and so it made sense to document JavaScript types. For other cases, I really think it's strictly better to use a tool designed for that job, like doxygen or javadoc, even though they make designers weep.

[trusktr]

My case is just JavaScript... that I've decided to port over to TypeScript. TypeDoc HTML output and its inference makes me weep.

I want to have simple good looking docs, based on what I write in my comments. TypeDoc gives me everything under the sun (f.e. I'm documenting Custom Element classes with a handful of properties/methods, and I really don't want to detract by showing all the things inherited from HTMLElement in every one of my classes; I could just point the user to MDN for that).

Not only do I want to simply document classes, but my classes are mixin classes, which can be used as regular classes, as in

class Foo extends MixinClass {}

or

class Foo extends MixinClass.mixin(Bar) {}

. TypeDoc documents these very horribly. I basically want to manually document these as

/**
 * @class Foo
 * @extends MixinClass
 */

for the regular extends case, and

/**
 * @class Foo
 * @implements MixinClass
 * @implements Bar
 */

or

/**
 * @class Foo
 * @extends MixinClass
 * @extends Bar
 */

for the mixin case. Or something simple along those lines.

Seems like there isn't anything that quite fits my need.

I am debating just making a separate docs folder and writing all docs in Markdown, without a doc generator tool, because of all the headache with all the tools.

[trusktr]

I must be a bad luck magnet when it comes to docs!

Here's a project, and the documentation script in package.json outputs an empty array:
https://github.com/infamous/infamous/tree/documentation/documentation-issue-1272