Advanced Ajax Architecture and Best Practices; Shawn M. Lauriat (Prentice Hall, 2008)

Podstrony

[ Pobierz całość w formacie PDF ]
.*/abstract public function getCache($key);/*** Deletes from cache a previously cached value* @param string $key The identifier for the cached variable* @return Boolean Returns a Boolean as to the success of the* deletion.*/abstract public function deleteCache($key);}API Documentation 281The updated memcacheCache comments add only the use of the @var tag, addingmetadata to the comment for the $memcache class variable.The comments for the methods(aside from the class __construct), lacking comments of their own, simply will inheritthe documentation from the parent Cache class documentation:/*** An abstraction class for the memcache extension, which* offers much more functionality than exposed here,* but this example keeps the object interface generic.*/class memcacheCache extends Cache {/*** The abstracted memcache instance* @var Memcache $memcache*/protected $memcache;public function setCache($key, $value = null, $expires = null) {return $this->memcache->set($key, $value, null, $expires);}public function getCache($key) {return $this->memcache->get($key);}public function deleteCache($key) {return $this->memcache->delete($key);}/*** This simple implementation defaults to one server: localhost.* It easily could pull in configuration information for* any number of memcache servers.*/public function __construct() {$this->memcache = new Memcache();$this->memcache->connect( 127.1 , 11211);}}By using these tags, the API documentation now has the associated comments in-cluded, but more importantly, they are included in a certain context.The @param-tagged282 Chapter 9 Documentinginformation now presents itself as information specifically regarding method parameters,@return-tagged information now appears as a return-specific comment and also as thereturn type in the method line itself, and the @var-tagged information associates itselfwith the object variable (see Figure 9.4).FIGURE 9.4 Class documentation as generated with minor changes to the comments.Comments parsed by phpDocumentor have another 27 block-level tags, like thethree described previously, available for a diverse range of purposes, along with anadditional eight inline tags.The tool also offers another twenty command-line options,spanning output control, template usage, naming, formatting, and categorization.However, as stated earlier, even the API documentation generated with only defaultAPI Documentation 283settings and no extra effort put into the comments themselves can prove extremelyuseful for developers.9.2.2 JSDocThe JSDoc project also parses inline documentation in comments as inspired by Java-Doc, but for JavaScript source files.Written in Perl, it requires only the installation ofPerl and the HTML::Template module.Perl should come preinstalled in most Linux/UNIX-based operating systems (includingMacOS X), and ActiveState offers a freely available ActivePerl runtime for Windows.Onceinstalled, running perl -MCPAN -e install HTML::Template installs the Perl modulerequired by JSDoc, after you answer some basic configuration questions from CPAN sinteractive prompts.The default output of JSDoc (show in Figure 9.5) has an even closer appearance toJavaDoc than phpDocumentor, and it includes the raw source code in the file overviews.FIGURE 9.5 The overview generated by JSDoc.284 Chapter 9 DocumentingThe following code, from Chapter 3, Client-Side Application Architecture,defines the core EventDispatcher class extended throughout the book.The class hasminimal inline comments, none of which exist in the block comment format:// Custom EventTarget equivalentfunction EventDispatcher() { }EventDispatcher.prototype = {// An object literal to store arrays of listeners by typeevents : {},// If it supports the type, add the listener (capture ignored)addEventListener : function(type, listener, capture) {if (this.events[type]) {this.events[type].push(listener);}},// If it supports the type, remove the listener (capture ignored)removeEventListener : function(type, listener, capture) {if (this.events[type] == undefined) {return;}var index = this.events[type].indexOf(listener);if (this.events[type][index]) {this.events[type].splice(index, 1);}},// Cycle through all event listeners, passing the event to callbacksdispatchEvent : function(type, event) {if (this.events[type]) {for (var i in this.events[type]) {if (typeof this.events[type][i] == 'function') {this.events[type][i](event);// Accepts an array of the contextual object// and the function to call} else if (typeof this.events[type][i] == object ) {this.events[type][i][1].call(this.events[type][i][0],event);}}}}}API Documentation 285JSDoc, as with phpDocumentor, generates informative API documentation evenwithout any usable comments in the code itself.Figure 9.6 shows the output after run-ning JSDoc on the above class definition, without having the ability to parse any of thenon-block comments.Though jsdoc.pl has a number of command-line options for use,all examples here use jsdoc.pl -d /Library/WebServer/Documents/js_docs_out applicationin order to specify the full path to the output directory (set with the -d flag) and to passthe root directory of the included JavaScript libraries to the script.FIGURE 9.6 Class documentation as generated without any changes to the comments.JSDoc also uses a number of comment tags to associate metadata and commentswith specific syntactical aspects of the code.The same class, written next with commentblocks, uses some of these tags in order to add context to the comments and also to someof the syntax itself, because a function definition in JavaScript may or may not define286 Chapter 9 Documentingthe constructor of a class, for instance.By using the @construct, the comment blockasserts that the function EventDispatcher() { } line of code does define the construct oftheEventDispatcher class.This block also includes the @require tag, signifying that theEventDispatcher class must have the CustomEvent class included in the same scope./*** Custom EventTarget equivalent* @requires CustomEvent* @construct*/function EventDispatcher() { }EventDispatcher.prototype = {/*** An object literal to store arrays of listeners by type*/events : {},/*** If it supports the type, add the listener (capture ignored)* @param {String} type The type of event to add the listener to* @param {Object} listener Either a function reference or an array* containing references to the function and the object within whose* context the function needs to run.* @param {boolean} capture Unused, just emulating real events*/addEventListener : function(type, listener, capture) {if (this.events[type]) {this.events[type] [ Pobierz całość w formacie PDF ]

zanotowane.pl

doc.pisz.pl

pdf.pisz.pl

bezglutenowo.pev.pl