From e5cfd6da73cfd496ec6c6c4248c18fb0cbbbf98c Mon Sep 17 00:00:00 2001 From: Daniel Molina Date: Wed, 20 Jan 2016 16:49:47 +0100 Subject: [PATCH] Add documentation examples to the sunstone README --- src/sunstone/public/README.md | 75 ++++++++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 5 deletions(-) diff --git a/src/sunstone/public/README.md b/src/sunstone/public/README.md index d626a41fee..a614139413 100644 --- a/src/sunstone/public/README.md +++ b/src/sunstone/public/README.md @@ -20,17 +20,26 @@ Sunstone dependencies Building minified JS and CSS files ================================== -4. Run the following command to generate the app.css file in the css folder: +The dependencies defined in the previous section must be instaled before running these commands: + +Option A - Grunt +---------------- + +* Run the following command to generate the app.css file in the css folder: + ``` grunt sass ``` -5. Run the following command to generate the minified js files in the dist foler + +* Run the following command to generate the minified js files in the dist foler and the app.min.css in the css folder: + ``` grunt requirejs ``` These are the files generate by the grunt requirejs command: + ``` css app.min.css @@ -40,10 +49,11 @@ These are the files generate by the grunt requirejs command: spice.js spice.js.map vnc.js vnc.js.map ``` -Scons -===== +Option B - Scons +---------------- + +Scons includes an option to build the minified JS and CSS files. -Scons includes an option to build the minified JS and CSS files. Steps 1, 2 and 3 have to be performed before running this command ``` scons sunstone=yes ``` @@ -52,3 +62,58 @@ Install.sh ========== By default the install.sh script will install all the files, including the non-minified ones. Providing the -p option, only the minified files will be installed. + +Documentation +============= + +[JSDoc](http://usejsdoc.org/) is used for the JS documentation. + +Examples +-------- + +* Parameters with properties + + ``` + /** + * Assign the project to an employee. + * @param {Object} employee - The employee who is responsible for the project. + * @param {string} employee.name - The name of the employee. + * @param {string} employee.department - The employee's department. + */ + Project.prototype.assign = function(employee) { + // ... + }; + ``` + +* Optional parameter + + ``` + /** + * @param {string} [somebody] - Somebody's name. + */ + function sayHello(somebody) { + if (!somebody) { + somebody = 'John Doe'; + } + alert('Hello ' + somebody); + } + ``` + +* Returns + + ``` + /** + * Returns the sum of a and b + * @param {Number} a + * @param {Number} b + * @param {Boolean} retArr If set to true, the function will return an array + * @returns {Number|Array} Sum of a and b or an array that contains a, b and the sum of a and b. + */ + function sum(a, b, retArr) { + if (retArr) { + return [a, b, a + b]; + } + return a + b; + } + ``` +