Pages

Sunday, April 30, 2017

ApexDoc A Salesforce Code Documentation Tool

ApexDoc A Salesforce Code Documentation Tool


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:myprojectclasses", 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:myprojectclasses D:homehtml D:myhome.html D:myauthor.txt

It will generate documentation of all "*.cls" files containing under "D:myprojectclasses" folder and output will be generated under "D:homehtml" 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:myprojectclasses

It will generate documentation in current folder of given source directory "D:myprojectclasses".

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

Blog Archive