[IPython-dev] JavaScript docs...

[Matthias BUSSONNIER]

Brian, 

You are probably writing more JS than I am, so whatever will suit you
I'll go with that, none the less a few comment inline

Le 6 juil. 2013 à 01:43, Brian Granger a écrit :

> Today, I have been working a lot on the dual mode editor stuff for the
> notebook.  Obviously, this means spending lots of time in the
> JavaScript code.  Part of our JavaScript development workflow is
> broken.  Namely the convention we are using for our JavaScript
> "docstring" is completely unworkable from a development standpoint:
> 
> * Managing comments in multiline /* */ style comments is horrific

As Aaron wrote, this should be the problem in your editor, I personally have
no problem with it, except maybe for re hard-wrapping long line that is sometime
confused. 

> * The visual clutter of the docstrings makes it very difficult to make
> your way around the code
> * It is painful enough that these docstrings easily fall out of sync

For those 2 I don't see where this differ from python. The format of the doctoring
is not particularly big, I personally have a light gray that is not disturbing. 
It is true that when you have loads of 1 line methods it take space.


> When we first went this route for our JavaScript docstrings, I thought
> to myself "I don't like this, but I will get used to it, just like I
> did with Python docstrings."  Unfortunately, the exact opposite has
> happened - my frustration has grown.  In the spirit of GitHub, we need
> to change this in order to "optimize for developer happiness."

I really don't want people to be angry at writing code, if it make you angry, 
we shoudl fix it.


> 
> Here is what I propose: I don't care one bit that we can generate
> official API docs from our JavaScript code.  If someone is really
> going to use our JS code, API docs won't go very far - they will need
> to look at the code eventually.

This is the main point where I disagree. I often use the API doc especially on user-exposed code
like cell toolbar, where it is really difficult to understand what the function does/how to use it without the docstring
especially when one need to pass a callback. and the ability to put markdown in doctoring that will be highlighted 
in doc is nice.

I agree that cell doc is almost useless : 
http://elacave.lmdb.eu/~carreau/yui/classes/IPython.Cell.html
But you can't say that the cell toolbar one is not much more friendlier than the code.
http://elacave.lmdb.eu/~carreau/yui/classes/IPython.CellToolbar.html


>  Let's come up with a standard that is
> easier to write and maintain for developers...any ideas?

would changing the comment delimiter help you like // ?
it might be possible to have comment like 

/**
//
// docstring.
//
//
*/ 

would this be better ?

we could limit docstrings to some specific functions that are not easy to use, or to figure out what they do.
This would diminish the amount of clutter you seem to feel. 

-- 
Matthias