Input file is not defined with CLI

[JulianCataldo]

Hello,

npx ts-doc-gen-md -i 'test.d.ts' -o "./test.md"

Yields:

undefined:1
test.d.ts
^

ReferenceError: test is not defined

Maybe I'm using the CLI wrong?

Thanks.

[lillallol]

Hello. Give me a day or two and I will come back with an answer.

[lillallol]

Fix

Try this on the terminal:

npx ts-doc-gen-md -i "'test.d.ts'" -o "'./test.md'"

Explanation

The values provided to the CLI are evaluated:

const pathInput = eval("'test.d.ts'");
const pathOutput = eval("'./test.md'");

Why things work this way

In short, because when I was creating them I was inexperienced.

The future

The future is discontinuing ts-doc-gen-md, together with fn-to-cli which is the library that creates CLI from TS functions, which by the way is using eval. They are both unnecessary over-engeering and I learnt that the hard way, by spenting so much time to create them.

ts-doc-gen-md

I have come to the conclusion that there is no need for documentation generation libraries. All I suggest you to do is to create a single index.d.ts file that will contain all of your public API (make sure that the private API depends on the public API, and not the other way around). This file will act like your documentation but also the typings entry point for your package.json. Like this you will not need to compile for .d.ts files, and people can read the documentation in their favorite familiar IDE environment which contains the syntax highlighting and keyboard shortcuts (collapse, expand, search) they are used to. Just add a documentation section in your README.md that will point to the index.d.ts so that people know where to find the documentation for your library.

fn-to-cli

If you were to import the function tsDocGenMd in a file, from the package ts-doc-gen-md you would get all the benefits an IDE provides together with typescript: syntax highliting, intellisense, JSDoc documentation, types, linting. Also you would not face the context issue. These do not exist on a CLI. This is not your fault. It is my fault, for providing a CLI. CLIs are unnecessary, at least for this case. You should just import functions in .js files and execute them via node. This is way much more simple. Not having to create a CLI for your library simplifies the workflow for both the consumer but also the maintainer.

[JulianCataldo]

Thanks for your detailed insights!

Have you tried https://github.com/TypeStrong/typedoc though?

Nice for populating docs website.

[lillallol]

Have you tried https://github.com/TypeStrong/typedoc though?

It is because I was not satisfied with typedoc back then, that I created ts-doc-gen-md. Right now, for the most cases, I consider using a documentation generation library an anti-pattern.

Nice for populating docs website.

I would avoid creating a website.

Instead of this:

https://github.com/lillallol/dic/blob/master/src/publicApi.ts

I would just give a dev link:

https://github.dev/lillallol/dic/blob/master/src/publicApi.ts

In fact what ts-doc-gen-md do is creating .md files out of .d.ts files. Why not just treat the .d.ts file as documentation then?