Start to document Javascript #2571

Merged
merged 10 commits into from Dec 4, 2012

Conversation

Projects
None yet
3 participants
@Carreau
Owner

Carreau commented Nov 12, 2012

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

This comment has been minimized.

Show comment Hide comment
@Carreau

Carreau Nov 12, 2012

Owner

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

Owner

Carreau commented Nov 12, 2012

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

@Carreau

This comment has been minimized.

Show comment Hide comment
@Carreau

Carreau Nov 13, 2012

Owner

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

Owner

Carreau commented Nov 13, 2012

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

@Carreau

This comment has been minimized.

Show comment Hide comment
@Carreau

Carreau Nov 16, 2012

Owner

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

Owner

Carreau commented Nov 16, 2012

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

@Carreau

This comment has been minimized.

Show comment Hide comment
@Carreau

Carreau Nov 17, 2012

Owner

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

Owner

Carreau commented Nov 17, 2012

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

@Carreau

This comment has been minimized.

Show comment Hide comment
@Carreau

Carreau Nov 29, 2012

Owner

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.

Owner

Carreau commented Nov 29, 2012

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

This comment has been minimized.

Show comment Hide comment
@ellisonbg

ellisonbg Nov 30, 2012

Owner

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.
Owner

ellisonbg commented Nov 30, 2012

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

This comment has been minimized.

Show comment Hide comment
@jasongrout

jasongrout Nov 30, 2012

Owner

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

Owner

jasongrout commented Nov 30, 2012

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

@ellisonbg

This comment has been minimized.

Show comment Hide comment
@ellisonbg

ellisonbg Nov 30, 2012

Owner

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/ipython/ipython/pull/2571#issuecomment-10897629.

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

Owner

ellisonbg commented Nov 30, 2012

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/ipython/ipython/pull/2571#issuecomment-10897629.

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

@ellisonbg

This comment has been minimized.

Show comment Hide comment
@ellisonbg

ellisonbg Nov 30, 2012

Owner

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/ipython/ipython/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

Owner

ellisonbg commented Nov 30, 2012

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/ipython/ipython/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

This comment has been minimized.

Show comment Hide comment
@Carreau

Carreau Nov 30, 2012

Owner

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/ipython/ipython/pull/2571#issuecomment-10897116.

Owner

Carreau commented Nov 30, 2012

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/ipython/ipython/pull/2571#issuecomment-10897116.

@ellisonbg

This comment has been minimized.

Show comment Hide comment
@ellisonbg

ellisonbg Nov 30, 2012

Owner

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/ipython/ipython/pull/2571#issuecomment-10906672.

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

Owner

ellisonbg commented Nov 30, 2012

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/ipython/ipython/pull/2571#issuecomment-10906672.

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

@Carreau

This comment has been minimized.

Show comment Hide comment
@Carreau

Carreau Dec 4, 2012

Owner

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

Do we add a static build somewhere on IPython website ?

Owner

Carreau commented Dec 4, 2012

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

Do we add a static build somewhere on IPython website ?

Carreau added a commit that referenced this pull request Dec 4, 2012

Merge pull request #2571 from Carreau/jsdoc
Start to document Javascript

see IPython/frontend/html/notebook/static/js/readme on how to compile/see it.

@Carreau Carreau merged commit c4fc493 into ipython:master Dec 4, 2012

1 check passed

default The Travis build passed
Details
@ellisonbg

This comment has been minimized.

Show comment Hide comment
@ellisonbg

ellisonbg Dec 4, 2012

Owner

Great, thanks for this work!

Owner

ellisonbg commented Dec 4, 2012

Great, thanks for this work!

mattvonrocketstein pushed a commit to mattvonrocketstein/ipython that referenced this pull request Nov 3, 2014

Merge pull request #2571 from Carreau/jsdoc
Start to document Javascript

see IPython/frontend/html/notebook/static/js/readme on how to compile/see it.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment