JavaScript PHP Documentor: Generate documentation for Javascript scripts

============================================================================================================================
						JSPD - JavaScript PHP Documentor

Author: Rafael M. Salvioni (rafael.salvioni @ gmail.com)
Page Design: http://code.google.com/p/jspd/
============================================================================================================================


1- Introduction
----------------

The JSPD is a library for creating documentation of JavaScript scripts based on comments
Special inserted within the JavaScript files. Very similar to JavaDoc.

The JSPD is written using the PHP 5 language, so to run it is necessary to have PHP installed
on the computer.


2- Installation
----------------

The JSPD can run on both Windows and Linux operating systems.

Unzip the zipped file to any folder you like. After you unpack it, edit
executable (in Windows systems, edit the file "jspd.bat" and Linux, edit the "jspd.sh") with a text editor.

Set the path to the folder where the interpreter of PHP is installed and ready.


3- Building the documentation
------------------------------

To generate the documentation, just run the "jspd" (.bat or .sh, depending on the system)
with the following parameters:

	- Name of the JavaScript library that will serve as the title of the documentation;
	- Directory where the JavaScript scripts;
	- Directory where the documents will be saved;
	- Description of the JavaScript library;
	- Driver of export (see below)

The JSPD will scan the specified directory (including subdirectories) behind files that have a known Extensions
by him. Such extensions are: .js, .htm, .html, .php and .asp.

After finding the files, the JSPD will open them and capture the special comments contained therein.
In possession of such comments, the JSPD will build a hierarchy so that the project can be worked
in many ways.


4- Drivers of export
---------------------

The JSPD was built to support the generation of documentation in various formats. By default,
a documentation JSPD creates the only HTML, but you can create documents in PDF, XML and other formats.

This is possible with the use of the drivers of export. When the JSPD starts, he assembles the entire hierarchy
Project and stores in a single object. This object has several methods to perform operations on the project.
Accordingly, half the job is done. In possession of the project graduated, the JSPD passes this project
the driver of export chosen, and this makes the job of generating the documentation. 

	4.1- Building drivers of export
	--------------------------------

	To build the drivers of export, we need a knowledge medium of language PHP. So I am assuming
	That the reader has this knowledge.

	The JSPD is nothing more than a set of classes that work with special comments and create a hierarchy of objects
	Based on them. All these classes are defined in the file "lib.php".

	For example, we shall build on the driver called "test".

	The first step is to create a folder called "test" in the root folder of JSPD. After,
	you must create a file "teste.php" folder inside the "test" newly created.

	After that, open the file "teste.php" and create a function called "jspd_teste" which receives 2 arguments:
	The first is the object of the project JSPD created and the second is the directory path of export.

	There, the driver was created. Now just set the contents of the function "jspd_teste" to have the same
	manages the documentation as desired and use the word "test" in the corresponding argument
	JSPD to run.

	If we wanted to create a driver called "example", we should just follow the steps above
	taking care to replace the word "test" with "example".
	
	
5- Commenting on the JavaScript files
--------------------------------------

As already stated, the JSPD works based on special comments inserted into the JavaScript file.
Thus, those comments have a special way of being written.

All comments must be started with the characters "/*#" and finalized as "#*/", both without the quotation marks.
Comments can be in one or more lines.

Within the comments are included special tags that represent the various comments that the information store.
Each tag begins with an "@" followed by the name of the tag.

Avoid using the character "@" outside the definitions of tags. The same applies to the comment delimiters.

There are 6 kinds of comments: File (file), Variable (var), Function (function), Class (class), Method (method) and Property
(property). These types are added in the comments as if they were tags.

If you do not have any comments one of 6 types specified, an error will be generated.

Below are some examples of comments.

	5.1- Files
	-----------
	Comments from files should contain the tag "@file". The string that follows the tag is disregarded. The other tags
	Used are:
		- @desc: Description
		- @author: Author of the file. It may contain more than one tag. 
		
	Example:
		/*#
		@file
		@desc My test file
		@author First author
		@author Second author
		#*/
		

	5.2- Variables
	---------------
	They represent variables.
	Comments of variables must contain the tag "@var" followed by the name of the variable. The other tags used are:
		- @type: Type of variable
		- @desc: Description
		- @author: Author of the variable. It may contain more than one tag. 
		
	Example:
		/*#
		@var test
		@type Integer
		@desc Test var
		@author First author
		@author Second author
		#*/
		var test = 1;

		
	5.3- Functions
	---------------
	They represent functions.
	Comments of office should contain the tag "@function" followed by the name of the function. The other tags used are:
		- @return: Type of return of function. If omitted, attaches itself to the type "void"
		- @param: Parameter of the function. The syntax of the parameter should be the following:
			(Type) (Name) (description). If the parameter is optional, the definition should be placed in
			brackets. You can have more than one tag.
		- @desc: Description
		- @author: Author of the function. It may contain more than one tag. 
		
	Example:
		/*#
		@function Concat
		@param String str1 String 1
		@param String str2 String 2
		@param [String str3 String 3]
		@return String
		@desc Concat two or more strings
		@author First author
		@author Second author
		#*/
		function Concat(str1, str2, str3) {
			return str1 + str2 + str3;
		}

		
	5.4- Classes
	-------------
	They represent a class.
	Comments of classes must contain the tag "@class" followed by the name of the class. The other tags used are:
		- @desc: Description
		- @author: Author of the class. It may contain more than one tag
		- @extends: Informs the class of which defined the class extends
		- @abstract: Tells if the class is abstract. It is not necessary any value 
		
	Example:
		/*#
		@class MyClass
		@desc My test class
		@extends MyParentClass
		@abstract
		@author First author
		@author Second author
		#*/
		.... Class definition .....

		
	5.5- Methods
	-------------
	They represent a class of methods.
	Comments methods to contain the tag "@ method" followed by the name of the method. The methods may contain exactly
	the same tags of the comments of staff, plus the following tags:
		- @abstract: Tells whether the method is abstract. It is not necessary any value
		- @static: Tells whether the method is static. It is not necessary any value

	The methods will be incorporated into the last class that has been set, so that if there is a defined class,
	An error is generated. 
		
	Example:
		/*#
		@method Concat
		@param String str1 String 1
		@param String str2 String 2
		@param [String str3 String 3]
		@return String
		@desc Concat two or more strings
		@author First author
		@author Second author
		#*/
		function Concat(str1, str2, str3) {
			return str1 + str2 + str3;
		}
		
	5.6-Properties
	---------------
	They represent properties of a class.
	Comments of properties must contain the tag "property @" followed by the name of the property. The properties may
	contain exactly	the same tags of the comments of Variable plus the following tags:
		- @abstract: Tells if the property is abstract. It is not necessary any value
		- @static: Tells if the property is static. It is not necessary any value

	The properties are entered in the last class that has been set, so that if there is a defined class,
	An error is generated. 
		
	Example:
		/*#
		@property test
		@type Integer
		@desc Test propertie
		@author First author
		@author Second author
		@static
		@abstract
		#*/
		var teste = 1;
		
		
6 - Final comments
------------------------

The project goal is to help programmers JSPD or teams of programmers to organize your files and document JavaScript
so that others can also use the code that has already been written.

Contributions and suggestions are welcome. Criticism will be accepted.

For more information, visit the homepage of the project: http://code.google.com/p/jspd/