ApexDoc - A Salesforce Code Documentation Tool

Tuesday, January 25, 2011 by Aslam - The Alexendra
Hi All,
Most of you java people may be familar with "javadoc" utility, and who are not from java they must know about good code documentation :).

A good documentation is always a good thing for your project for long term success. A good documentation contains well defined comments, usage, public methods used, their parameters, return types, author, dates etc. Generally documentations used for a open source project or a library projects, so that if any new person is using your library or project then he will get good help about that easily.

I am working in Salesforce about 3 years with lot of Apex coding. I also created some libraries in Apex also. I wanted something similar documentation for my work using same like javadoc. But i could not found any tool exist for that. So started this utility project in java. My main moto is to make it as simpler as 'javadoc' command. So, here comes my 'apexdoc'.

Guidelines to use apexdoc:-

Go to here http://www.aslambari.com/apexdoc.html and download the "apexdoc" java client. You can also find one screen cast there. Its a zip, so after download, unzip it on your disc, for example D:\apexdoc.

Command Syntax:-

apexdoc <source_directory> [<target_directory?>] [<homefile>] [<authorfile>]

1) source_directory :- The folder location which contains your apex .cls classes. Ideally it is the folder 'classes' under your Eclipse IDE project setup on disc under "src" subfolder. I think best is that you should first copy that classes folder somewhere on disc for example "D:\myproject\classes\", and use this as source folder.

2) target_directory :- This option is optional. This is to specify your target folder where documentation will be generated. If not given then it will generates the output documentation into current directory.

3) homefile :- This option is optional. This is to specify your contents for the home page right panel, Ideally it contains the project information for which you making documentation and it MUST be in html format containing data under tags.

4) authorfile :- This option is optional. This is a simple text file path containing following info.

---------------------
projectname=<project name will be shown on top header>
authorname=<author name will be shown on top header>
email=<email will be shown on top header>

sampleauthor.txt
----------------------
projectname=my project
authorname=Aslam Bari
email=aslam.bari@gmail.com

5) Ideally if you need logo at top of your documentation header, you must put your file under your target directory with name logo.jpg with dimension.

Sample commands:-
1) Sample 1:-

apexdoc D:\myproject\classes D:\home\html D:\myhome.html D:\myauthor.txt

It will generate documentation of all "*.cls" files containing under "D:\myproject\classes" folder and output will be generated under "D:\home\html" folder with name "ApexDocumentation", your home page will contain project info from "D:\myhome.html" file, and your header will get contents from D:\myauthor.txt file.

2) Sample 2:-
apexdoc D:\myproject\classes

It will generate documentation in current folder of given source directory "D:\myproject\classes".

If all goes fine you will get one good documentation of all your classes, public properties and public methods generated. One sample generated output is here:-


Guidelines for comments and code:-

You code must have two types of comments. One for Classes, one for Methods. By default all public properties will be fetched in documentation, no need for comments for them.
Comments must start with /** and ends with */
Following attributes are supported for now:-

@author
@date
@param
@param
---(multiple @param supported)
@description
@return


Some sample code with comments as below:-

/**
* @author Aslam Bari
* @date 25/01/2011
* @description Class calculates some accounting information based on user experience and given methods. Usually user need to make one object of the class and call methods direcly.
*/

public class Accounting{
public string accountNo {get;set;}
public Integer discount {get;set;}
public string bankname {get;set;}

private string balance = 0;


/**
* @author Mark P
* @date 25/01/2011
* @description It accepts one account number and discount from external
user and calculates some info based on user profile and return the total price.
* @param accountNumber Users account number
* @param discount discount applicable for the user
* @return Double Price calculated after calculating based on profile
*/
public double calculatePrice(string accountNumber, integer discount){
-----------------
-----------------
-----------------
return price;
}

}

This tool is in Beta version and may contains bugs. I would like to get your feedbacks on this and will surely enhance this tool based on your reported bugs and feedback. Reach me at aslam.bari@gmail.com

Thanks
Aslam Bari

211 comments:

«Oldest   ‹Older   201 – 211 of 211   Newer›   Newest»
sobiga J said...

Thank you for useful inoformation!

Iot Training in Chennai
Big data Hadoop Training in chennai

srinivasulu said...

Thanks. Nice blog!! Very useful information is providing by your blog. Great tutorial about
Best digital marketing workshop in chennai

srinivasulu said...

Thanks for such a knowledgeable post.We provide Best SEO services in Chennai
please visit:
digital marketing classes in chennai

dushyant sharma said...

Webtrackker Indirapuram, recognized among the top ten software testing training institute in Indirapuram, has a training module for beginners, intermediates and experts. If you are a university student, I.T professional or a project manager the best software testing training institute in Indirapuram offers the best training environment, veteran software testing trainers and flexible training schedules for complete modules. In addition, the best training institute for software testing training in Indirapuram asks for a value to the students' money rate. Students of all professions can pay the fee structure of the Software Testing courses.
software testing institute in Indirapuram

aashutosh webtrackker said...

Aws online training in india

Salesforce online training in india

aashutosh webtrackker said...

Aws online training in india

Salesforce online training in india

aashutosh webtrackker said...

Salesforce online training in india

Aws online training in india

Hadoop online training in INDIA


Mahesh said...

thanks for sharing this blog. This very important and informative blog for then who do Salesforce
I really loved reading this. Keep it up.!!

Best Salesforce training in Gurgaon

dushyant sharma said...

NEW YEAR OFFERS 2018

Flipkart New Year Offers on Mobile Phones


Ebay New Year Offers On Mobile Phones

srinivasulu said...

Thanks for sharing about digital marketing,your blog always brought some useful information,i hope you will share more article like that...
digital marketing classes in chennai

dushyant sharma said...

SEO Company In Cape Town

SEO company in Durban

SEO Company in india
SEO company in Johannesburg

«Oldest ‹Older   201 – 211 of 211   Newer› Newest»

Post a Comment