1173675 - link gaia jsdoc gh-page on per app readme

Status: RESOLVED FIXED

(Firefox OS Graveyard :: Gaia, defect)

Description

[[e-mail]]

link jsdoc such as http://mozilla-b2g.github.io/gaia/settings/ on per app readme. It will help new contributors to grasp our code base better.

Comment 1

[[e-mail]]

Attachment: pull request for settings

The generated jsdoc is now hosting on gh-pages http://mozilla-b2g.github.io/gaia/settings/ . Add link on readme to help contributor grasp our code.

Comment 2

[[e-mail]]

Attachment: pull request for calendar

The generated jsdoc is now hosting on gh-pages http://mozilla-b2g.github.io/gaia/calendar/ . Add link on readme to help contributor grasp our code.

Comment 3

[[e-mail]]

Attachment: pull request for camera

The generated jsdoc is now hosting on gh-pages http://mozilla-b2g.github.io/gaia/camera/ . Add link on readme to help contributor grasp our code.

Comment 4

[Justin D'Arcangelo [:justindarc]]

Comment on attachment 8620846 [details] [review]
pull request for camera

LGTM. Thanks!

Comment 5

[Arthur Chen [:arthurcc][inactive after 6/30]]

Comment on attachment 8620839 [details] [review]
pull request for settings

r=me, thanks.

Comment 6

[[e-mail]]

settings https://github.com/mozilla-b2g/gaia/commit/4f35cfd5d5a91c8f34fd138badfbdfca9253d35d
camera https://github.com/mozilla-b2g/gaia/commit/70f676b76be30c1185358d6ed4823fba0c343644

thanks!

Comment 7

[[e-mail]]

Attachment: pull request for apps

The generated jsdoc is now hosting on gh-pages http://mozilla-b2g.github.io/gaia/<app_name>/ . Add link on readme to help contributor grasp our code.

Comment 8

[[e-mail]]

Attachment: pull request for system

The generated jsdoc is now hosting on gh-pages http://mozilla-b2g.github.io/gaia/system/ . Add readme and jsdoc link to help contributor grasp our code.

Comment 9

[Rudy Lu [:rudyl] (inactive after 2015/7/3)]

Comment on attachment 8622330 [details] [review]
pull request for apps

Looks good to me, please help take a look at the nits I commented on the pr.
Thank you.

Comment 10

[Jim Porter (:squib)]

It seems a bit strange to me to put this in every subdirectory's README, rather than just in the main README...

Comment 11

[James Burke [:jrburke]]

Comment on attachment 8622330 [details] [review]
pull request for apps

I agree with :squib, seems fine just to do in the main readme instead of each app.

For email specifically: while we use some jsdoc-like comments in email, it is more to aid in the source code reading, not to really be useful as generated docs. The end result: the generated docs are not very useful, particularly since we do not use the tags for jsdoc to recognize modules.

So I would prefer for email to just not include the jsdoc mention in the readme: to me that indicates we are suggesting that it might be useful when in the current state it is not. 

Perhaps with this new jsdoc infrastructure it would be possible for use to now do comment changes in email to then make it useful, but I think it is too soon for email's readme to suggest users looking at the generated output.

Comment 12

[[e-mail]]

As james said not all app use or recommend to document with jsdoc, user will feel frustrated while checking the main README but linked to a void document.

I'd remove jsdoc section in email. And ringtone as well if :squib prefer so.

Comment 13

[Steve Chung [:steveck]]

Comment on attachment 8622330 [details] [review]
pull request for apps

LGTM, thanks!

Comment 14

[Jim Porter (:squib)]

Comment on attachment 8622330 [details] [review]
pull request for apps

I checked the generated docs for Ringtones, and like E-mail, they're not very good. Most of the function comments aren't getting picked up (probably because of how Ringtones defines some of its modules), so in the interest of not confusing people, I don't think we should advertise the Ringtones docs.

Comment 15

[[e-mail]]

Ok it's totally up to module owner to decide if its proper or not to add the link on README. I'll remove Ringtones docs from the PR.

Comment 16

[[e-mail]]

system PR merged https://github.com/mozilla-b2g/gaia/commit/720e38c5140272ea38fcedc142b4395e443632c7

Comment 17

[[e-mail]]

:mmedeiros thanks for calendar review. could you help review clock part as well?

Comment 18

[Miller Medeiros [:millermedeiros]]

Comment on attachment 8622330 [details] [review]
pull request for apps

Clock documentation is not going to help contributors in any way. I think the same can be said about the Calendar documentation as well. JSDoc is not recognizing the modules (everything is displayed as part of the "Global" namespace) and there are very few documented methods.

I initially assumed that all the apps needed links to JSDoc, only now I realized it is optional.

Comment 19

[Miller Medeiros [:millermedeiros]]

Comment on attachment 8620842 [details]
pull request for calendar

changed my mind, JSDoc is not helping in any way and might confuse contributors. sorry about that.

Comment 20

[[e-mail]]

It's fine I'll leave calendar and clock jsdoc not listed in README.

Comment 21

[[e-mail]]

merged for sms, keyboard, camera https://github.com/mozilla-b2g/gaia/commit/9ea3792b58302d15d99caa643f9472a4885b6485