[IPython-dev] JavaScript docs...

[Fernando Perez]

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