[jira] [Comment Edited] (ARROW-951) [JS] Fix generated API documentation

["Brian Hulette (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/ARROW-951?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16595187#comment-16595187 ] 

Brian Hulette edited comment on ARROW-951 at 9/11/18 3:50 PM:
--------------------------------------------------------------

I think [this typedoc issue|https://github.com/TypeStrong/typedoc/issues/159] 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 https://github.com/TypeStrong/typedoc/pull/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.


was (Author: bhulette):
I think [this typedoc issue|https://github.com/TypeStrong/typedoc/issues/159] is relevant to our problem. Using "--mode module" 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 https://github.com/TypeStrong/typedoc/pull/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.

> [JS] Fix generated API documentation
> ------------------------------------
>
>                 Key: ARROW-951
>                 URL: https://issues.apache.org/jira/browse/ARROW-951
>             Project: Apache Arrow
>          Issue Type: Task
>          Components: JavaScript
>            Reporter: Brian Hulette
>            Priority: Minor
>              Labels: documentation
>             Fix For: JS-0.4.0
>
>
> 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.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)