Surface more code docs.

Surface more code docs.

Sorry for the big branch. A good chunk of it is the regenerated
"undocumented" file.

This branch goes over all 20 main source files, and gets most
comment blocks out of there and into the generated pages. It
rearranges the module and class directives so that all the
code parts are reachable from the pages. It also adds some
comment blocks to modules, classes and methods: the
undocumented count is now down to 173.

https://code.launchpad.net/~teknico/juju-gui/surface-more-code-docs/+merge/147431

(do not edit description out of merge proposal)

[teknico, 2013-02-08 17:55:46]

Please take a look.

[gary.poster, 2013-02-08 18:05:39]

Land as is.  Really nice cleanups.  Thank you.

Gary

[bac, 2013-02-08 18:12:05]

Thanks Nicola -- nice changes.  Land with changes, please.

https://codereview.appspot.com/7312067/diff/1/app/app.js
File app/app.js (right):

https://codereview.appspot.com/7312067/diff/1/app/app.js#newcode37
app/app.js:37: *
Could you elaborate on this comment as I'm not sure what the problem is.  Why
isn't this documentation in the generated output?  I see this comment is
repeated a lot.

https://codereview.appspot.com/7312067/diff/1/app/models/charm.js
File app/models/charm.js (right):

https://codereview.appspot.com/7312067/diff/1/app/models/charm.js#newcode177
app/models/charm.js:177: */
Thanks for fixing this formatting.  This style of bad format keeps sneaking back
into the code.  Maybe 'bzr blame' and let the dev know?

https://codereview.appspot.com/7312067/diff/1/app/store/charm.js
File app/store/charm.js (right):

https://codereview.appspot.com/7312067/diff/1/app/store/charm.js#newcode14
app/store/charm.js:14: *
This comment is useless.  What is a charm store?  What does it provide?

https://codereview.appspot.com/7312067/diff/1/app/store/charm.js#newcode81
app/store/charm.js:81: * owned charms follow, sorted again by relevance if
available and package
relevance, if available, and

https://codereview.appspot.com/7312067/diff/1/app/store/notifications.js
File app/store/notifications.js (right):

https://codereview.appspot.com/7312067/diff/1/app/store/notifications.js#newc...
app/store/notifications.js:76: * config properties.
The spelling 'ad hoc' is preferred.

https://codereview.appspot.com/7312067/diff/1/app/store/notifications.js#newc...
app/store/notifications.js:155: *
Please add a '.' for punctuation.  (Or maybe a '!' if you're passionate about
delta streams.)

https://codereview.appspot.com/7312067/diff/1/app/views/charm.js
File app/views/charm.js (right):

https://codereview.appspot.com/7312067/diff/1/app/views/charm.js#newcode8
app/views/charm.js:8: *
This looks more like an XXX candidate than a module-level description.

https://codereview.appspot.com/7312067/diff/1/app/views/login.js
File app/views/login.js (right):

https://codereview.appspot.com/7312067/diff/1/app/views/login.js#newcode16
app/views/login.js:16: *
Non-informative.

https://codereview.appspot.com/7312067/diff/1/app/views/topology/topology.js
File app/views/topology/topology.js (right):

https://codereview.appspot.com/7312067/diff/1/app/views/topology/topology.js#...
app/views/topology/topology.js:5: *
:/

[teknico, 2013-02-08 18:25:26]

Not great answers, I know. At least I made the changes you asked for. :-)

https://codereview.appspot.com/7312067/diff/1/app/app.js
File app/app.js (right):

https://codereview.appspot.com/7312067/diff/1/app/app.js#newcode37
app/app.js:37: *
On 2013/02/08 18:12:05, bac wrote:
> Could you elaborate on this comment as I'm not sure what the problem is.  Why
> isn't this documentation in the generated output?  I see this comment is
> repeated a lot.

I have no idea. I cannot see why the "behaviors" attribute is shown in the
output, but the "views" one is not.

https://codereview.appspot.com/7312067/diff/1/app/models/charm.js
File app/models/charm.js (right):

https://codereview.appspot.com/7312067/diff/1/app/models/charm.js#newcode177
app/models/charm.js:177: */
On 2013/02/08 18:12:05, bac wrote:
> Thanks for fixing this formatting.  This style of bad format keeps sneaking
back
> into the code.  Maybe 'bzr blame' and let the dev know?

Yes, someone should do just that, sometimes. :-)

https://codereview.appspot.com/7312067/diff/1/app/store/charm.js
File app/store/charm.js (right):

https://codereview.appspot.com/7312067/diff/1/app/store/charm.js#newcode14
app/store/charm.js:14: *
On 2013/02/08 18:12:05, bac wrote:
> This comment is useless.  What is a charm store?  What does it provide?

You are right, the text is not useful. I know it's not nice to add apparently
useless comment blocks, but I needed to get at least all the classes in the
output, and given the breadth of this change, did not have the time to make each
addition meaningful.

https://codereview.appspot.com/7312067/diff/1/app/store/charm.js#newcode81
app/store/charm.js:81: * owned charms follow, sorted again by relevance if
available and package
On 2013/02/08 18:12:05, bac wrote:
> relevance, if available, and

Done.

https://codereview.appspot.com/7312067/diff/1/app/store/notifications.js
File app/store/notifications.js (right):

https://codereview.appspot.com/7312067/diff/1/app/store/notifications.js#newc...
app/store/notifications.js:76: * config properties.
On 2013/02/08 18:12:05, bac wrote:
> The spelling 'ad hoc' is preferred.

Done.

https://codereview.appspot.com/7312067/diff/1/app/store/notifications.js#newc...
app/store/notifications.js:155: *
On 2013/02/08 18:12:05, bac wrote:
> Please add a '.' for punctuation.  (Or maybe a '!' if you're passionate about
> delta streams.)

Done.

https://codereview.appspot.com/7312067/diff/1/app/views/charm.js
File app/views/charm.js (right):

https://codereview.appspot.com/7312067/diff/1/app/views/charm.js#newcode8
app/views/charm.js:8: *
On 2013/02/08 18:12:05, bac wrote:
> This looks more like an XXX candidate than a module-level description.

It is true. Probably the idea to get this more visible in the output is not a
great one. I'll put it back in the shade.

https://codereview.appspot.com/7312067/diff/1/app/views/login.js
File app/views/login.js (right):

https://codereview.appspot.com/7312067/diff/1/app/views/login.js#newcode16
app/views/login.js:16: *
On 2013/02/08 18:12:05, bac wrote:
> Non-informative.

See above.

https://codereview.appspot.com/7312067/diff/1/app/views/topology/topology.js
File app/views/topology/topology.js (right):

https://codereview.appspot.com/7312067/diff/1/app/views/topology/topology.js#...
app/views/topology/topology.js:5: *
On 2013/02/08 18:12:05, bac wrote:
> :/

You wanted this branch even bigger than it is? :-)

[teknico, 2013-02-08 18:29:05]

Please take a look.

[teknico, 2013-02-08 18:35:22]

*** Submitted:

Surface more code docs.

Sorry for the big branch. A good chunk of it is the regenerated
"undocumented" file.

This branch goes over all 20 main source files, and gets most
comment blocks out of there and into the generated pages. It
rearranges the module and class directives so that all the
code parts are reachable from the pages. It also adds some
comment blocks to modules, classes and methods: the
undocumented count is now down to 173.

R=gary.poster, bac
CC=
https://codereview.appspot.com/7312067