Skip to content

Conversation

@TheNeuralBit
Copy link
Member

@TheNeuralBit TheNeuralBit commented Jan 30, 2021

Also ran npm audit fix

This PR upgrades us beyond typedoc 0.20 which made significant improvements to how re-exported objects are handled. I've uploaded a preview of the generated docs at https://theneuralbit.github.io/arrow-typedoc-0.20/. Compare this to the existing API docs at http://arrow.apache.org/docs/js/index.html.

It properly reflects our two top-level modules, Arrow.dom and Arrow.node, and shows the objects exported within them. The existing docs give the impression of a bag of objects without any structure.

There's still a lot of work to do to make these API docs useful, but I think this is a big step in the right direction (many thanks to @Gerrit0 for all the typedoc improvements that made this possible) . Some remaining issues that we could file follow-up jiras for:

  • Some objects are missing (e.g. Vector sub-classes like DateVector, FloatVector, ..). These also seem to be missing from the existing docs. It's possible this is a bug in typedoc? Will need further investigation.
  • Many classes and methods are still completely undocumented, so API docs tell users little aside from the structure of the code.

@TheNeuralBit TheNeuralBit requested a review from trxcllnt January 30, 2021 19:08
@github-actions
Copy link

Thanks for opening a pull request!

Could you open an issue for this pull request on JIRA?
https://issues.apache.org/jira/browse/ARROW

Then could you also rename pull request title in the following format?

ARROW-${JIRA_ID}: [${COMPONENT}] ${SUMMARY}

See also:

@TheNeuralBit TheNeuralBit changed the title [ARROW-951] Upgrade to typedoc 0.20.19 ARROW-951: [JS] Upgrade to typedoc 0.20.19 Jan 30, 2021
@github-actions
Copy link

@TheNeuralBit
Copy link
Member Author

One issue with this change - it will break existing links. For example the docs for Table moved from classes/table.html to classes/arrow_dom.table.html.

We could fix this by only generating using one entryPoint - either Arrow.dom.ts or Arrow.node.ts (or Arrow.ts), not both.

@trxcllnt
Copy link
Contributor

trxcllnt commented Feb 1, 2021

@TheNeuralBit I think we have /** @ignore */ on the vector subclasses, so they're excluded from the list of documented types.

@domoritz
Copy link
Member

domoritz commented Feb 1, 2021

The new docs look great. The initial organization is a bit odd, though. There is a Module in the menu on the side with the two actual modules that are already listed below.

Screen Shot 2021-02-01 at 13 30 00

@nealrichardson
Copy link
Member

Merging; please feel free to make followup JIRAs. Plenty of time to polish the docs before the next release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants