Let's add a documentation
to our Todo
list application in Chapter 1, Getting Started with JavaScriptMVC.
To add the main documentation page, create a Markdown file todo.md
in the Todo/todo
directory with the following content:
@page index TodoApp @description TodoApp is simple todo application. # TodoApp documentation Here we can add some more documentation formatted by [Markdown][1]! [1]: http://daringfireball.net/projects/markdown/syntax "Check out Markdown syntax"
Then, add these documentation blocks to the todo.js
file:
steal( 'jquery/class', 'jquery/model', 'jquery/util/fixture', 'jquery/view/ejs', 'jquery/controller', 'jquery/controller/route', function ($) { /** * @class Todo * @parent index * @constructor * @author Wojciech Bednarski * Creates a new todo. */ $.Model('Todo',{ /** * @function findAll * Get all todos * @return {Array} an array contains objects with all todos */ findAll: 'GET /todos', /** * @function findOne * Get todo by id * @return {Object} an objects contains single todo */ findOne: 'GET /todos/{id}', /** * @function create * Create todo * @param {Object} todo * Todo object * @codestart * {name: 'read a book by Alfred Szklarski'} * @codeend * * @return {Object} an object contains newly created todo * @codestart * { * id: 577, * name: 'read a book by Alfred Szklarski' * } * @codeend * * ### Example: * @codestart * var todo = new Todo({name: 'read a book by Alfred Szklarski'}); * todo.save(function (todo) { * console.log(todo); * }); * @codeend */ create: 'POST /todos', /** * @function update * Update todo by id * @return {Object} an object contains updated todo */ update: 'PUT /todos/{id}', /** * @function destroy * Destroy todo by id * @return {Object} an object contains destroyed todo */ destroy: 'DELETE /todos/{id}' }, { } ); // Fixtures (function () { var TODOS = [ // list of todos { id: 1, name: 'read The Good Parts' }, { id: 2, name: 'read Pro Git' }, { id: 3, name: 'read Programming Ruby' } ]; // findAll $.fixture('GET /todos', function () { return [TODOS]; }); // findOne $.fixture('GET /todos/{id}', function (orig) { return TODOS[(+orig.data.id) - 1]; }); // create var id = 4; $.fixture('POST /todos', function () { return { id: (id++) }; }); // update $.fixture('PUT /todos/{id}', function () { return {}; }); // destroy $.fixture('DELETE /todos/{id}', function () { return {}; }); }()); /** * @class Todos * Creates a new Todos controller * @parent index * @constructor * @param {String} DOMElement DOM element * @return {Object} */ $.Controller('Todos', { // init method is called when new instance is created 'init': function (element, options) { this.element.html('todos.ejs', Todo.findAll()); }, // add event listener to strong element on click 'li strong click': function (el, e) { // trigger custom event el.trigger('selected', el.closest('li').model()); // log current model to the console console.log('li strong click', el.closest('.todo').model()); }, // add event listener to em element on click 'li .destroy click': function (el, e) { // call destroy on the model to prevent memory leaking el.closest('.todo').model().destroy(); }, // add event listener to Todo model on destroyed '{Todo} destroyed': function (Todo, e, destroyedTodo) { // remove element from the DOM tree destroyedTodo.elements(this.element).remove(); console.log('destroyed: ', destroyedTodo); } }); /** * @class Routing * Creates application router * @parent index * @constructor * @param {String} DOMElement DOM element * @return {Object} */ $.Controller('Routing', { init: function () { new Todos('#todos'), }, // the index page 'route': function () { console.log('default route'), }, // handle URL witch hash ':id route': function (data) { Todo.findOne(data, $.proxy(function (todo) { // increase font size for current todo item todo.elements(this.element).animate({fontSize: '125%'}, 750); }, this)); }, // add event listener on selected '.todo selected': function (el, e, todo) { // pass todo id as a parameter to the router $.route.attr('id', todo.id); } }); // create new Routing controller instance new Routing(document.body); } );
Type directives represent JavaScript constructs that you may want to document:
@page
: This adds a standalone page@attribute
: These are the document values on an object@function
: These are document functions@class
: This documents a class@prototype
: This is added to the previous class or a constructor's prototype functions@static
: This is added to the previous class or constructor's static functions@add
: This adds the docs to a class or constructor described in another fileTag directives provide additional information to the comments:
@alias
: This specifies other commonly used names for class or constructor@author
: This specifies the author of a class@codestart
: This specifies the start of a code block@codeend
: This specifies end of a code block@constructor
: This documents a contractor function and its parameters@demo
: This is the placeholder for an application demo@description
: This is used to add a short description@download
: This is used to adds download link@iframe
: This is used to add an iframe with example code@hide
: This hides the class view@inherits
: This specifies what the Class or Constructor inherits@parent
: This specifies under which parent the current type should be located@param
: This specifies a function parameter@plugin
: This specifies a plugin by which an object gets stolen@return
: This specifies what a function returns@scope
: This forces the current type to start the scope@tag
: This specifies the tags for searching@test
: This specifies the links for test cases@type
: This sets the type for the current commented code@image
: This adds an image3.129.26.108