Javascript Documentation

Hey rmehta!

I was thinking maybe follow the jsdoc conventions or something similar: http://usejsdoc.org/

If frappe will one day generate it’s own javascript documentation through bench perhaps it would be simpler to follow their conventions?

so for example I was thinking on file “frappe/public/js/frappe/ui/dialog.js”:

Flag file as part of the frappe.ui module:
/**
* @module frappe.ui
*/

Then on functions on the same file:
/**
* Frappe UI Dialog
* @class
/
frappe.ui.Dialog = frappe.ui.FieldGroup.extend({
/
*
* @constructor
* @param {object} opt - Dialog options
*/
init: function(opts) { … },

    /**
     * Creates the dialog dom structure
     * @private
     */
    make: function() { ... },

    /**
     * Sets input focus on first input element
     */
    focus_on_first_input: function() { ... },

    /**
     * Gets the primary button jquery wrapped element
     * @returns {jQuery}
     */
    get_primary_btn: function() { ... },

    /**
     * Sets the primary button labe and click action.
     * @param {string} label - The primary button label.
     * @param {function} click - The action function callback triggered by primary button click event.
     * @returns {jQuery} Returns the primary button jquery wrapped element.
     */
    set_primary_action: function(label, click) { ... }

    ...
});

JSDoc is a node module and would be easy to setup for developers but I’m not sure if you want that dependency.

@Felipe_Orellana Thanks let me get back to you!

@Felipe_Orellana thanks for starting this conversation

I am thinking we can use a more minimal style (similar to python) and maybe tweak our current docs generator to generate JS docs too.

What do you think?

    //- Creates the dialog dom structure
    make: function() { ... },

    //- Sets input focus on first input element
    focus_on_first_input: function() { ... },

    //- Gets the primary button jquery wrapped element
    get_primary_btn: function() { ... },

    //- Sets the primary button label and click action and returns the primary button jquery wrapped element.
    //  :param {string} label: The primary button label.
    //  :param {function} click: The action function callback triggered by primary button click event.
    set_primary_action: function(label, click) { ... }

    ...
});

Ah, yeah that’s a lot closer to python.

That’s looks pretty clean, but javascript IDEs wouldn’t know how to pick up the new syntax. However, maybe bench could generate virtual jsdoc(files only containing jsdoc formatted documentation) or other formats from these?

Either way, if leveraging what is already available on the doc generator is easier I’m down for that.

@Felipe_Orellana yeah lets do this simpler one (it will also make for smaller files)

Once you have a few pages done, i will update setup_docs.py so that it will start creating pages for JS files too!

@Felipe_Orellana made this public

Awesome

I’ll start going through a few js files and start documenting this way. Pull requests are sufficient for this right?

2 Likes