documentationjs
It's not clear how to run this on TypeScript files (f.e. it produces empty docs)
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.
I contributed TS parsing support. I have not used it with the built in documentation CLI though. I've been using it with gatsby.
Does that mean you're using it with the Node API? It would be helpful to know how to use that too.
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
Hmm, and with no options other than shallow. I guess that doesn't help to know why the CLI fails.
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.
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?
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.
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...
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.
I'll try giving this a look. The JavaScript ecosystem is… chaotic. Thanks to Webpack, lots of folks started ~~ab~~using 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.
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.
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
I just realized, Leafdoc is "language-agnostic", or basically has a "polyglot" mode like documentation.js v4 had, which I think is what I need after having tried a bunch of tools, because polyglot mode will give me freedom to specify documentation exactly how I want to without source code inference doing what I don't want, and without source code syntax making the parser fumble, etc.
For now I'll give Leafdoc's "polyglot" mode a try because it is actively supported.
I haven't tried Documentation.js's v4 "polyglot" mode yet though, but while Leafdoc has that mode, and also allows any @class to extend from any number of other @classes (multiple inheritance) while being source-code agnostic, I think this will give me the flexibility that I'm looking for.
I know I will duplicate type from my TypeScript source in my doc comments, but I think it's worth the flexibility (semantic types don't need to line up with actual source types, and semantic types may be the same across languages, while actual source types can vary).
Before realizing that Leafdoc had a polyglot mode, I was thinking to just write comments in markdown format, and processing them by stripping all source, then rendering to HTML. The downside is more boilerplate across files for formatting, but the upside is total control.
(I hope these aren't totally useless remarks. I hope it helps to know what people in the community are looking for.)
I tried running documentation build src/** -f html -o docs on my TypeScript project and it spat out something totally empty. Can't find any mention of TypeScript in the documentation. Should I be using something else?
@revmischa I've been wanting to try the "polyglot" mode of documentation.js v4.x.x that @tmcw mentioned above, which can run on any files agnostic of the source code. Maybe that'll work.
On another note, Leafdoc may be an alternative.
Leafdoc can run on any file (it looks for C-like comments regardless of source). After getting accustomed to the syntax, it is running well on my TypeScript files.
Leafdoc is very simple, which is nice. It doesn't use JSDoc syntax unfortunately, but it works.
@tmcw Assuming I have a project containing src/**/*.ts files, can you give a quick example of how to run v4 on those files in polyglot mode?
Just came across the same issue.. I got mine working by using the parameter --parse-extension ts as seen in the top-posting.
@SantoJambit nailed it! I'd update the README / docs, but I am not sure where you guys would want that information. We really should make that flag known for folks that are using Typescript with this library.
Readme would be fine for me.. it's the first place I start looking for information. A file in the docs folder would be the next best thing (with a link from the readme obviously).
Unfortunately even if --parse-extension ts and --require-extension .ts arguments are applied, it still wont resolve any imported typescript files.
--pe ts --re ts --re d.tsworked for me. Thanks for the hints posted here.
Unfortunately that does not work, when combined with --document-exported.
