[JS] Fix generated API documentation

[asfimport]

The current generated API documentation doesn't respect the project's namespaces, it simply lists all exported objects. We should see if we can make typedoc display the project's structure (even if it means re-structuring the code a bit), or find another approach for doc generation.

Reporter: Brian Hulette / @TheNeuralBit
Assignee: Brian Hulette / @TheNeuralBit

Related issues:

• [JS] Implement JavaScript-compatible implementation (Is contained by)

PRs and other links:

• GitHub Pull Request #9375

_{Note: This issue was originally created as ARROW-951. Please see the migration documentation for further details.}

[asfimport]

Wes McKinney / @wesm:
[~paul.e.taylor] are we at a place where we could generate API docs for the JS library?

[asfimport]

Brian Hulette / @TheNeuralBit:
I can run typedoc on our current implementation if I use the branch from this PR, which adds support for the version of TypeScript we're using. I'll work on generating/publishing this once we get #1482 merged

[asfimport]

Arun Shanmugam Kumar:
I am looking into this currently to help on the doc generation for JS.

[asfimport]

Uwe Korn / @xhochy:
@TheNeuralBit is this also covered by #1647 ?

[asfimport]

Brian Hulette / @TheNeuralBit:
@xhochy sort of.. we already have generated API documentation that was added as part of a previous PR, but we're not quite happy with the current output since it doesn't respect the project structure (it just lists every class/function but not what namespace they're in). [~arunsk] is looking into fixing that.

In the meantime, there's still value in the current docs, so I thought we could go ahead and publish them.

Do you think we should update this JIRA to reflect the actual task, or just mark it resolved and make a new one?

[asfimport]

Uwe Korn / @xhochy:
@TheNeuralBit just update it to match what should be done.

[asfimport]

Wes McKinney / @wesm:
What is the state of this?

[asfimport]

Brian Hulette / @TheNeuralBit:
I think this typedoc issue is relevant to our problem. Using "-mode modules" and "-tsconfig tsconfig/tsconfig.es2015.cjs.json" actually generates some pretty reasonable output, but it doesn't show any of the modules that are re-exported in src/Arrow.ts, it only shows them in their original locations (e.g. this would imply you should import Table with import \{ Table \} from 'apache-arrow/table; rather than import \{ Table \} from 'apache-arrow';. Both are valid, but we encourage the latter in our documentation and tutorials, so it would be nice if the API docs reflected that.

https://github.com/iRath96/typedoc (outdated) and TypeStrong/typedoc#646 both claim to resolve this issue. We should test those out and see if we can help get them merged if they work for us.

[asfimport]

Wes McKinney / @wesm:
@TheNeuralBit any luck on this one? I'm removing from any release milestone for the time being

[asfimport]

Brian Hulette / @TheNeuralBit:
With the typedoc 0.20 release we can generate much better API docs. I'll send a PR.

[asfimport]

Neal Richardson / @nealrichardson:
Issue resolved by pull request 9375
#9375