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 file
Tag 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 image
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.