Start to document Javascript

[Carreau]

Ok,
I looked at documenting javascript.

The 2 main school are :

• structured comment designed for JS
• inline comment with markdown/html

Or a mixed of the two.

I choose the first so that you could explicitely add things like @deprecated, @class , @static.

Among those the difference in language is minimal. with most of the keywords in common and a few difference here and there like you to make crosslink.

lots of people like JsDoc and show it by forking it and adding incompatible option, so that v2 is almost 2 years old and has 4 implementation with different behavior. And the official one is deprecated.

v3 is "on it's way" with bugs like template not working. Exception about parsing command line after outputing half of the doc. Link in the doc not working.
But it is the one that require the less human work as it figures out itself if stuff are methods, static, ...Etc

The other good one I found was YUI doc, which more duplicate work (retype @method methodname for each methods), but
work out of the box. Is maintained. Has lots of users. Has good docs ! support markdown in comment. Works in general better.

So this is mostly targetting YUIdoc (http://yui.github.com/yuidoc/)

Comment starting with /** (2 stars) , keyword beginnig with @, above each function.

Does this suite everyone ?
Should we start forcing ourselves do document every JS function that we modify in this way ?

I'll add doc building with yuidoc on a separate PR.
(YIU doc docs are build with yui doc, if you want to see)

[Carreau]

sorry for the early post,tab space is not my friend.

[Carreau]

more doc and add readme on how to build/view the doc

[Carreau]

Moving forward, still no review..
If we make some JS documentation, do we try to include it in sphinx ?

[Carreau]

and here is how it looks like. default theme, can be changed.

[Carreau]

As this is only and purely docs, without objection i'll merge it tomorrow.
Hopefully it will force us to write more JS docs along the way.

[ellisonbg]

A few comments:

• I agree we need to document our JS code and that yuidoc is probably a good option. Not worried about a node dependency as we are going to start to depend on other things in node.
• Is there a way to use regular // style comments. I find the /** */ style tedious to type and visually distracting.

[jasongrout]

I'm curious: what are the other node dependencies that you foresee?

[ellisonbg]

A few things:

We are probably going to eventually want to start running jslint on our JS
code.

We also will want to combine/minimize our JS.

We are going to start using Bootstrap and less and will want the ability to
compile less into css.

On Fri, Nov 30, 2012 at 9:49 AM, Jason Grout notifications@github.comwrote:

I'm curious: what are the other node dependencies that you foresee?

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2571#issuecomment-10897629.

Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com

[ellisonbg]

But, as you can see these will be requirements to develop the notebook, not
to run it.

On Fri, Nov 30, 2012 at 9:52 AM, Brian Granger ellisonbg@gmail.com wrote:

A few things:

We are probably going to eventually want to start running jslint on our JS
code.

We also will want to combine/minimize our JS.

We are going to start using Bootstrap and less and will want the ability
to compile less into css.

On Fri, Nov 30, 2012 at 9:49 AM, Jason Grout notifications@github.comwrote:

I'm curious: what are the other node dependencies that you foresee?

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2571#issuecomment-10897629.

Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com

Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com

[Carreau]

Short from my phone.
Sorry, no way to escape /** as beginning of documentation.

Ok for merge?
Le 30 nov. 2012 18:30, "Brian E. Granger" notifications@github.com a
écrit :

A few comments:

• I agree we need to document our JS code and that yuidoc is probably
  a good option. Not worried about a node dependency as we are going to start
  to depend on other things in node.

• Is there a way to use regular // style comments. I find the /** */style tedious to type and visually distracting.

  —
  Reply to this email directly or view it on GitHubhttps://github.com/Start to document Javascript #2571#issuecomment-10897116.

[ellisonbg]

I am not thrilled about this syntax, but I guess it is unavoidable. That
is one area where Python rocks with triple quoted strings!

On Fri, Nov 30, 2012 at 2:31 PM, Bussonnier Matthias <
notifications@github.com> wrote:

Short from my phone.
Sorry, no way to escape /** as beginning of documentation.

Ok for merge?
Le 30 nov. 2012 18:30, "Brian E. Granger" notifications@github.com a
écrit :

A few comments:

• I agree we need to document our JS code and that yuidoc is probably
  a good option. Not worried about a node dependency as we are going to
  start
  to depend on other things in node.
• Is there a way to use regular // style comments. I find the /**
  */style tedious to type and visually distracting.

—
Reply to this email directly or view it on GitHub<
https://github.com/ipython/ipython/pull/2571#issuecomment-10897116>.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2571#issuecomment-10906672.

Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com

[Carreau]

Sorry about /** i'm going to merge as this is a huge improvement.

Do we add a static build somewhere on IPython website ?

[ellisonbg]

Great, thanks for this work!