[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