Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ARROW-951: [JS] Upgrade to typedoc 0.20.19 #9375

Closed
wants to merge 1 commit into from

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.

@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
Contributor

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

nevi-me pushed a commit to nevi-me/arrow that referenced this pull request Feb 13, 2021
Also ran `npm audit fix`

This PR upgrades us beyond [typedoc 0.20](https://github.com/TypeStrong/typedoc/releases/tag/v0.20.0) 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.

Closes apache#9375 from TheNeuralBit/typedoc-0.20

Authored-by: Brian Hulette <hulettbh@gmail.com>
Signed-off-by: Neal Richardson <neal.p.richardson@gmail.com>
GeorgeAp pushed a commit to sirensolutions/arrow that referenced this pull request Jun 7, 2021
Also ran `npm audit fix`

This PR upgrades us beyond [typedoc 0.20](https://github.com/TypeStrong/typedoc/releases/tag/v0.20.0) 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.

Closes apache#9375 from TheNeuralBit/typedoc-0.20

Authored-by: Brian Hulette <hulettbh@gmail.com>
Signed-off-by: Neal Richardson <neal.p.richardson@gmail.com>
michalursa pushed a commit to michalursa/arrow that referenced this pull request Jun 13, 2021
Also ran `npm audit fix`

This PR upgrades us beyond [typedoc 0.20](https://github.com/TypeStrong/typedoc/releases/tag/v0.20.0) 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.

Closes apache#9375 from TheNeuralBit/typedoc-0.20

Authored-by: Brian Hulette <hulettbh@gmail.com>
Signed-off-by: Neal Richardson <neal.p.richardson@gmail.com>
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.

None yet

4 participants