[IPython-dev] JavaScript docs...

[Brian Granger]

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
* 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

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

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.  Let's come up with a standard that is
easier to write and maintain for developers...any ideas?

Cheers,

Brian

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