[jsdoc] Enable generate all apps/ jsdoc

RESOLVED FIXED in 1.4 S6 (25apr)

Status

defect
RESOLVED FIXED
6 years ago
5 years ago

People

(Reporter: gasolin, Assigned: gasolin)

Tracking

unspecified
1.4 S6 (25apr)
ARM
Gonk (Firefox OS)
Dependency tree / graph

Firefox Tracking Flags

(Not tracked)

Details

Attachments

(2 attachments)

46 bytes, text/x-github-pull-request
yurenju
: review+
yurenju
: feedback+
timdream
: feedback+
Details | Review
56 bytes, text/x-github-pull-request
yurenju
: review+
Details | Review
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.
Assignee: nobody → gasolin
can generate all apps' jsdoc
Attachment #8356004 - Flags: review?(timdream)
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?
Attachment #8356004 - Flags: review?(timdream) → feedback?(yurenju.mozilla)
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.
Attachment #8356004 - Flags: feedback?(yurenju.mozilla) → feedback+
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
...
Flags: needinfo?(yurenju.mozilla)
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...
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.
Flags: needinfo?(yurenju.mozilla)
Blocks: 972785
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.
Attachment #8356004 - Flags: review?(yurenju.mozilla)
I feel the xfail files should exist in apps directory. what do you think?
Flags: needinfo?(gasolin)
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.
Flags: needinfo?(gasolin)
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 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
Attachment #8356004 - Flags: review?(yurenju.mozilla)
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.
Attachment #8356004 - Flags: review?(yurenju.mozilla)
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.
Attachment #8356004 - Flags: review?(yurenju.mozilla)
Posted file PR for node_module
Attachment #8408150 - Flags: review?(yurenju.mozilla)
Comment on attachment 8356004 [details] [review]
pull request redirect to github

Addressed comments in github, please kindly review it again
Attachment #8356004 - Flags: review?(yurenju.mozilla)
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.
Attachment #8356004 - Flags: review?(yurenju.mozilla)
Attachment #8408150 - Flags: review?(yurenju.mozilla) → review+
Comment on attachment 8356004 [details] [review]
pull request redirect to github

updated to aggregate per app's jsdoc.json for configuration
Attachment #8356004 - Flags: review?(yurenju.mozilla)
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.
Attachment #8356004 - Flags: review?(yurenju.mozilla) → review+
merged https://github.com/mozilla-b2g/gaia/commit/551274b8abafc982c64fd54a58a79971edace720

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

thanks!
Status: NEW → RESOLVED
Closed: 5 years ago
Resolution: --- → FIXED
Target Milestone: --- → 1.4 S6 (25apr)
You need to log in before you can comment on or make changes to this bug.