[IPython-dev] JavaScript docs...
Fernando Perez
fperez.net at gmail.com
Sun Jul 7 02:38:36 EDT 2013
Just a couple of quick questions:
- is it possible to avoid all the * in the comments for the doc
generation machinery? Technically JS only needs the matching /* */
pair, so unless the doc tools need all the extra * on every line,
those could be skipped.
- it it OK to put the 'docstring' after the function declarations,
like in python?
If both of these were possible, we could have these JS 'docstrings'
looking like:
var Notebook = function (selector, options) {
/*
A notebook contains and manages cells.
@class Notebook
@constructor
@param {String} selector A jQuery selector for the notebook's
DOM element
@param {Object} [options] A config object
*/
var options = options || {};
instead of
/**
* A notebook contains and manages cells.
*
* @class Notebook
* @constructor
* @param {String} selector A jQuery selector for the notebook's DOM element
* @param {Object} [options] A config object
*/
var Notebook = function (selector, options) {
That seems quite a bit more python-like and readable to me...
Cheers,
f
On Fri, Jul 5, 2013 at 4: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
>
> 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
--
Fernando Perez (@fperez_org; http://fperez.org)
fperez.net-at-gmail: mailing lists only (I ignore this when swamped!)
fernando.perez-at-berkeley: contact me here for any direct mail
More information about the IPython-dev
mailing list