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

Proposal: Plugin docs generation #15

Closed
daserge opened this Issue Sep 4, 2015 · 6 comments

Comments

Projects
None yet
2 participants
@daserge
Contributor

daserge commented Sep 4, 2015

Cordova docs-gen proposal

Initial points for investigation were the following:

  • Code to Docs tool selection -> proposing JSDoc for following reasons:
    • JSDoc parses code-tree, which means smart code analysis, internal linking and less comments verbosity in code,
    • JSDoc is extensible via JS plugins,
    • JSDoc presentation is customizable via templates,
    • Existing code uses JSDoc format mostly;
  • Generated docs renderer selecting -> Use either JSDoc (HTML output) or jsdoc-to-markdown (md output),
  • Create JSDoc plugin for handling Cordova-specific tags like supported-platforms, quirks (or windows-quirks, android-quirks, ...), etc.,
    • Investigate possibility: Link to quirks/examples (similar to tutorial tag) instead of inlining to reduce noise in the code (this will also help as existing docs will be moved as is),
      • @partial plugin can be used for this purpose. Using it along with markdown plugin allows just to move big docs chunks from plugin docs to function/class-related files (there is also a @tutorial plugin, but it just inserts a link to separate file),
      • JSDoc @typedef tag can be used for linking to separate file - this has a drawback that separate file has to be in JSDoc comments format (while we have md);
  • Use custom JSDoc template to integrate with cordova-docs site,
    • The documentation will need to be rebuilt on each code change. Investigate a proper way to do this? (CI tools, precommit hook, prepackage hook for npm).

Prototypes:

Thoughts?
Perhaps there are some better tools or methods I have missed?

@daserge

This comment has been minimized.

Show comment
Hide comment
@daserge

daserge Sep 8, 2015

Contributor

Upd: After setting up underlying JSDoc and turning on partial and markdown plugins @partial worked.
Although there are issues with combining of @partial and other JSDoc tags like @param: see text after Tizen Quirks.

Contributor

daserge commented Sep 8, 2015

Upd: After setting up underlying JSDoc and turning on partial and markdown plugins @partial worked.
Although there are issues with combining of @partial and other JSDoc tags like @param: see text after Tizen Quirks.

@daserge daserge changed the title from Plugin docs generation to Proposal: Plugin docs generation Sep 9, 2015

@daserge

This comment has been minimized.

Show comment
Hide comment
@daserge

daserge Sep 9, 2015

Contributor

Used markdown-links in JSDoc comments to the moved big docs chunks (quirks, extra examples, etc.) to the Handlebars template file:
Result

How it works:

Contributor

daserge commented Sep 9, 2015

Used markdown-links in JSDoc comments to the moved big docs chunks (quirks, extra examples, etc.) to the Handlebars template file:
Result

How it works:

@daserge

This comment has been minimized.

Show comment
Hide comment
@daserge

daserge Sep 10, 2015

Contributor

Upd:

Summary instructions:

Contributor

daserge commented Sep 10, 2015

Upd:

Summary instructions:

@nikhilkh

This comment has been minimized.

Show comment
Hide comment
@nikhilkh

nikhilkh Sep 16, 2015

Contributor

@axemclion @dblotsky Can you please review and comment.

Contributor

nikhilkh commented Sep 16, 2015

@axemclion @dblotsky Can you please review and comment.

@daserge

This comment has been minimized.

Show comment
Hide comment
@daserge
Contributor

daserge commented Sep 16, 2015

@nikhilkh

This comment has been minimized.

Show comment
Hide comment
@nikhilkh

nikhilkh May 13, 2016

Contributor

@daserge We've already converted this to a proposal. Closing this now.

Contributor

nikhilkh commented May 13, 2016

@daserge We've already converted this to a proposal. Closing this now.

@nikhilkh nikhilkh closed this May 13, 2016

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