<div dir="ltr">On Fri, Jul 5, 2013 at 6:43 PM, Brian Granger <span dir="ltr"><<a href="mailto:ellisonbg@gmail.com" target="_blank">ellisonbg@gmail.com</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote">

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Today, I have been working a lot on the dual mode editor stuff for the<br>
notebook.  Obviously, this means spending lots of time in the<br>
JavaScript code.  Part of our JavaScript development workflow is<br>
broken.  Namely the convention we are using for our JavaScript<br>
"docstring" is completely unworkable from a development standpoint:<br>
<br>
* Managing comments in multiline /* */ style comments is horrific<br>
* The visual clutter of the docstrings makes it very difficult to make<br>
your way around the code<br>
* It is painful enough that these docstrings easily fall out of sync<br></blockquote><div><br></div><div>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.</div>

<div><br></div><div>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.</div><div><br></div><div>

I do agree that the @param nonsense gets old pretty fast.</div><div><br></div><div>Aaron Meurer</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
When we first went this route for our JavaScript docstrings, I thought<br>
to myself "I don't like this, but I will get used to it, just like I<br>
did with Python docstrings."  Unfortunately, the exact opposite has<br>
happened - my frustration has grown.  In the spirit of GitHub, we need<br>
to change this in order to "optimize for developer happiness."<br>
<br>
Here is what I propose: I don't care one bit that we can generate<br>
official API docs from our JavaScript code.  If someone is really<br>
going to use our JS code, API docs won't go very far - they will need<br>
to look at the code eventually.  Let's come up with a standard that is<br>
easier to write and maintain for developers...any ideas?<br>
<br>
Cheers,<br>
<br>
Brian<br>
<br>
--<br>
Brian E. Granger<br>
Cal Poly State University, San Luis Obispo<br>
<a href="mailto:bgranger@calpoly.edu">bgranger@calpoly.edu</a> and <a href="mailto:ellisonbg@gmail.com">ellisonbg@gmail.com</a><br>
_______________________________________________<br>
IPython-dev mailing list<br>
<a href="mailto:IPython-dev@scipy.org">IPython-dev@scipy.org</a><br>
<a href="http://mail.scipy.org/mailman/listinfo/ipython-dev" target="_blank">http://mail.scipy.org/mailman/listinfo/ipython-dev</a><br>
</blockquote></div><br></div></div>