956634 - [jsdoc] Enable generate all apps/ jsdoc

Status: RESOLVED FIXED

(Firefox OS Graveyard :: Gaia, defect)

Description

[[e-mail]]

Current jsdoc can only generate system (and keyboard in Bug 956627) jsdoc.

With `lenient` (tolerance) mode enabled, we can set jsdoc configurations ready first, then fix per app's syntax if any.

Comment 1

[[e-mail]]

WIP https://github.com/mozilla-b2g/gaia/pull/15025

Comment 2

[[e-mail]]

Attachment: pull request redirect to github

can generate all apps' jsdoc

Comment 3

[Tim Guan-tin Chien [:timdream] (please needinfo)]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

It would be better if we could pick up these config from a metadata descriptor within each app. List like this in the root is often forgotten and got out-dated.

Yuren, any good idea on where the data should be put?

Comment 4

[Yuren [:yurenju] (AFK ~ Oct. 12) (volunteer mode)]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

it would be better if split configuration file for each app and put config file into APP/build/docs.json or APP/docs.json.

Comment 5

[[e-mail]]

After read `maintainable grunt` http://www.thomasboyt.com/2013/09/01/maintainable-grunt.html

I just thinking if we can extend it to a more flexible structure for large project.
First step might be to make Grunt script structured like local makefile (but only handle grunt config at this moment) in each App.

ex: put and read config data from each App/Gruntconfig.json (follow naming rule as Gruntfile.js)

So the structure could be

/Gruntfile.js - define tasks
/apps/system/grunt/Gruntconfig.json - jsdoc (and other) config
/apps/keyboard/Gruntconfig.json - jsdoc (and other) config
...

Comment 6

[[e-mail]]

Found a plugin can get configs from apps/

https://github.com/el-fuego/grunt-local-settings


And there're some existing plugin that can run full Gruntfile.js in apps/ . such as 

https://github.com/DavidSouther/grunt-recurse
https://github.com/tusbar/grunt-subgrunt

So we may not need to reinvent the wheel...

Comment 7

[Yuren [:yurenju] (AFK ~ Oct. 12) (volunteer mode)]

sounds good, but could you also discuss this with Greg? if this feature isn't so critical we can put this change to Greg's experiment project.

Changing build tool is a big thing and I would like to have more discussion on dev-gaia mailing list for it.

Comment 8

[[e-mail]]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

update to cover more new apps.

Current grunt version act like xfail list, it's still worth to have a full doc gen before we make per-app doc gen in each app folder possible.

Comment 9

[Yuren [:yurenju] (AFK ~ Oct. 12) (volunteer mode)]

I feel the xfail files should exist in apps directory. what do you think?

Comment 10

[[e-mail]]

Sound's reasonable, but that will need to patch the grunt plugin to enable the inclusion... 

I could fire a followup bug to patch the grunt plugin and move current configs to separate jsdoc.json files.

Comment 11

[Yuren [:yurenju] (AFK ~ Oct. 12) (volunteer mode)]

could we just patch Gruntfile.js? it is a javascript and we can read and parse xfail files to an jsdoc and usue it in initConfig()

Comment 12

[[e-mail]]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

aha! I almost forget Gruntfile.js is js file, will do it before send review :D

Comment 13

[[e-mail]]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

I rewrite a bit to refer jsdoc_xfail.list in each app to exclude js files.

Comment 14

[Yuren [:yurenju] (AFK ~ Oct. 12) (volunteer mode)]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

see comments on github and set review flag to me if pull request is updated.

Comment 15

[[e-mail]]

Attachment: PR for node_module

Comment 16

[[e-mail]]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

Addressed comments in github, please kindly review it again

Comment 17

[Yuren [:yurenju] (AFK ~ Oct. 12) (volunteer mode)]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

discussed with Fred offline, the options will be moved to app directory then we can keep Gruntfile.js clean.

Comment 18

[Yuren [:yurenju] (AFK ~ Oct. 12) (volunteer mode)]

BTW. gasolin, please also update gaia_node_module.revision.

https://github.com/mozilla-b2g/gaia/blob/master/gaia_node_modules.revision

Comment 19

[[e-mail]]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

updated to aggregate per app's jsdoc.json for configuration

Comment 20

[Yuren [:yurenju] (AFK ~ Oct. 12) (volunteer mode)]

Comment on attachment 8356004 [details] [review]
pull request redirect to github

r=yurenju if nits are addressed and don't forget update gaia_node_modules.revision.

Comment 21

[[e-mail]]

merged https://github.com/mozilla-b2g/gaia/commit/551274b8abafc982c64fd54a58a79971edace720

node module https://github.com/mozilla-b2g/gaia-node-modules/commit/23d7549bcbc5cad24751da0adbb68c2c073864fe

thanks!