[IPython-dev] JavaScript docs...

Aaron Meurer asmeurer at gmail.com
Fri Jul 5 19:58:26 EDT 2013

On Fri, Jul 5, 2013 at 6:43 PM, Brian Granger <ellisonbg at gmail.com> wrote:

> 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

Maybe this isn't the answer you are looking for, but can't the first two
points be solved by a good text editor.  Emacs is smart enough to wrap
comments using a combination of auto-fill-mode and M-q. For the second
point, you just need a good code-folding tool.

To be fair, I don't use javascript, so I can't comment deeply on this.
 Actually, I just tested the Emacs javascript-mode, and the defaults seem
to have some rough edges.

I do agree that the @param nonsense gets old pretty fast.

Aaron Meurer

> 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
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20130705/0997cb0d/attachment.html>

More information about the IPython-dev mailing list