New API docs

[ahocevar]

API doc generation no longer works after #8345. We need to find a new tool chain to generate API docs.

Possible options:

1. A while ago, @tschaub and I started an effort in the site branch to use the output from tasks/generate-info.js as starting point for a Gatsby generated API documentation. This turns out to be a huge effort, almost equivalent to writing an API doc generator from scratch.

2. Investigate tools like ESDoc, TypeDoc or not-yet-available tools that may come out of Microsoft's TSDoc effort.

3. Generate *.d.ts files and see if there are tools to generate documentation from those.

Comments and thoughts on these options, or ideas for other options, are much appreciated.

[ahocevar]

I have investigated TypeDoc a bit. I did not find a way to make it work with *.js files. Maybe it works if we are able to generate d.ts files? If so, how can we create those?

[ahocevar]

I am now investigating ESDoc. Will report here how that goes, but currently I'm stuck with Cannot read property 'charAt' of undefined errors.

[ahocevar]

ESDoc does not support import() type annotations, that's the reason for the errors I mentioned above.

[ahocevar]

Actually there is hope that we can get things to work with TypeDoc. See TypeStrong/typedoc#643.

[ahocevar]

I have submitted TypeStrong/typedoc#824 to make TypeDoc work with typescript@next

[ahocevar]

Looks like even with the above pull request, TypeDoc does not work properly with @typedef and @enum annotations.

[gberaudo]

I am trying to make typedoc output something but I only get an empty documentation page:

git checkout ts
npm link typedoc  # to get latest version and I use typescript@next there
npx typedoc --out tsdoc src

@ahocevar, do you have a branch somewhere so I have a look to how you did it?

[ahocevar]

@gberaudo See https://github.com/openlayers/closure-es-modules/ for an example project. You need to set allowJs: 'true' in tsconfig.json's compilerOptions and use typedoc --tsconfig tsconfig.json to consume the configuration file.

[gberaudo]

Thanks for your input @ahocevar, it helped a lot.

Strangely my issue was coming from the way I invoked typedoc.
I was passing the source directory like this:

npx typedoc --out tsdoc src  # matches the documentation but produces empty output

When omitting the source directory it does something (it is specified in tsconfig.json anyway):

npx typedoc --out tsdoc  # does something

[ahocevar]

In the end, after way too much time spent trying to make TSDoc work for us, I went with JSDoc again. See #8847.

[marcjansen]

Have you ever considered using https://documentation.js.org ? I didn't check the features / configurability but we have been using in some smaller projects and we are quite happy with it.

[ahocevar]

@marcjansen I have, but it does not work well with modules, and not at all with TypeScript types unfortunately.

[marcjansen]

Thanks for the info, @ahocevar