@Felipe_Orellana Awesome
No just add simple notes on the top of the file or the function to start with.
I think that works best for now.
Maybe we can start a comprehensive API documentation sometime.
Send a PR with some samples before you make extensive changes.
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.
rmehta
September 17, 2016, 6:04am
2
@Felipe_Orellana Thanks let me get back to you!
rmehta
September 19, 2016, 6:49am
3
@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.
rmehta
September 20, 2016, 6:16am
5
@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!
rmehta
September 20, 2016, 6:17am
7
@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