PHP Classes
elePHPant
Icontem

JavaScript PHP Documentor: Generate documentation for Javascript scripts

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Info   Screenshots Screenshots   View files View files (11)   DownloadInstall with Composer Download .zip   Reputation   Support forum (1)   Blog    
Last Updated Ratings Unique User Downloads Download Rankings  
2010-03-16 (5 years ago) RSS 2.0 feedNot enough user ratingsTotal: 736 All time: 4,226 This week: 1,322Up
Version License PHP version Categories  
jspd 0.1GNU General Publi...5.0HTML, PHP 5, Utilities and Tools, Tex...
Description Author  

This class can be used to generate documentation for Javascript scripts.

It can scan Javascript script files and extract documentation from tags inside Javascript comments similar to JavaDoc tags.

The documentation can be generated in HTML using PHP template scripts.

However, the structure of package allows generate documentation in many others formats, like a PDF for example.

Innovation Award  
PHP Programming Innovation award nominee
October 2008
Number 3


Prize: One license of ScriptCase Enterprise edition
Despite it is a language almost as old as the first browsers, only in the latest years Javascript has been getting almost as importance in Web applications as server side languages.

Javascript libraries have grown significantly and they need to be documented.

This package can extract documentation from comments in the Javadoc format and produce HTML pages that allows the user to browse the different classes and functions contained in the Javascript scripts.

Manuel Lemos
Picture of Rafael M. Salvioni
Name: Rafael M. Salvioni <contact>
Classes: 2 packages by
Country: Brazil Brazil
Age: 32
All time rank: 106074 in Brazil Brazil
Week rank: 861 Up62 in Brazil Brazil Up
Innovation award
Innovation award
Nominee: 1x

Details provided by the author  
============================================================================================================================
						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/


Screenshots  
  • jspd.gif
  Files folder image Files  
File Role Description
Files folder imagedrivers (1 directory)
Plain text file jspd.bat Data JSPD windows executable
Plain text file jspd.php Appl. JSPD starter script
Plain text file jspd.sh Data JSPD linux executable
Plain text file lib.php Class JSPD Library File
Plain text file readme-en.txt Doc. English documentation
Plain text file readme-pt.txt Doc. Brazilian portuguese documentation

  Files folder image Files  /  drivers  
File Role Description
Files folder imagedefault (5 files)

  Files folder image Files  /  drivers  /  default  
File Role Description
  Plain text file class.tpl.php Aux. Template to class description pages
  Plain text file default.css Data CSS from documentation
  Plain text file default.php Aux. Default export driver
  Plain text file file.tpl.php Aux. Template from files documentation
  Plain text file menu.tpl.php Aux. Template from menu

 Version Control Unique User Downloads Download Rankings  
 0%Total:736All time:4,226
 This week:0This week:1,322Up
 User Comments (1)  
 
This is a good class !! lool
6 years ago (Josť Filipe Lopes Santos)
70%StarStarStarStar