Documenting code is super important for software development. It helps developers understand and work with the code better. Salesforce projects are no exception.
Why Do You Need to Document the Code?
With good documentation, you can navigate the code like a pro, making modifications with ease and avoiding any catastrophic changes. And let’s not forget about the newbies – with clear documentation, they can join the team and hit the ground running, instead of spending days trying to decipher what this Apex class is used for.
Why Are There Problems With Documentation?
There are a bunch of reasons why some companies don’t bother with code documentation. For one, it takes a lot of time and resources that some companies just don’t have. Plus, some developers might not realize how important it is to document their code, or they might not know how to do it well. And if there’s a tight deadline, documentation might get put on the back burner in favor of getting the product out the door.
Luckily, there are some tools to ease your documentation process. One of them is IcApexDoc, developed by Scott Wells, the creator of the Illuminated Cloud Salesforce development tool.
How Can IcApexDoc Tool Help You?
Let’s check out the IcApexDoc tool and see how it can help you generate documentation.
IcApexDoc is a free command-line tool that generates documentation from Salesforce source code and metadata, including Apex types and triggers, custom objects, and fields.
Advantages:
- automated generation
- HTML-based documentation that you can share freely across your team without giving access to the full code
- you will be able to examine Apex code no matter what IDE you are using, especially when it is a free IDE without complex functionality
The only must-have for a successful IcApexDoc usage is well-written comments.
How to Install IcApexDoc?
Getting started with IcApexDoc is very simple: download the latest released version of IcApexDoc.zip archive from the repo, extract it to your local file system, and add <extractedDirectory>/bin to your operating system’s execution path.
How Does It Work?
As I’ve mentioned before, clear comments for the code are a key to high-quality documentation. For popular development environments, there are ApexDoc plugins that help you write and format comments more conveniently and also help you avoid mistakes in them.
Keep in mind that ApexDoc comments are Apex block comments that begin with /**.
Now it’s an example time! Here is the code with comments that we will use to generate documentation via IcApexDoc.
/**
* @author Apex Class author
* @date creation date
* @description helper class validation methods
*/
public class FlsHelperClass {
/**
* @description map of available object fields
*/
private final Map <String, Schema.SObjectField> objectFields;
/**
* @description Class constructor
* @param objectName string name of the object to be checked for access
*/
public FlsHelperClass(String objectName) {
this.objectFields = Schema.getGlobalDescribe()
.get(objectName)
.getDescribe().fields.getMap();
}
/**
* @author method author
* @date creation date
* @description verify the permission to edit this field
* @param fieldName string name of the field to be checked
* @return `Boolean` value about the Edit permission
* @deprecated false
*/
public Boolean verifyCreateable(String fieldName) {
if (objectFields.get(fieldName).getDescribe().isCreateable()) {
return true;
}
throw new PermissionsException();
}
/**
* @author method author
* @date creation date
* @description verify the permission to read this field
* @param fieldName string name of the field to be checked
* @return `Boolean` value about the Read permission
* @exception PermissionException if a user doesn't have permission to read this field
*/
private Boolean verifyReadable(String fieldName) {
if (objectFields.get(fieldName).getDescribe().isAccessible()) {
return true;
}
throw new PermissionsException();
}
}
Also, I want to mention that when you’re making documentation for your project, you need to have the data you want to describe saved on your computer first as local files. Once you’ve got all the necessary data and added comments to the classes and methods, you can generate documentation for them. And if there’s any metadata you don’t want to include, you can exclude it during the generation process or just not save it to your computer.
The terminal command to generate documentation:
apexdoc -p sfdx-project.json -o apexdoc -v private -x /libs/metadataservice
Where:
–p required argument for specifying the source of the project file
–o the directory in which the generated documentation will be saved
-x argument that specifies the directory that you want to exclude from the documentation
–v minimum level of access to a class or method (public – by default)
Well done! Now open the file apexdox/index.html in your browser, and you’ll be taken to the documentation’s home page. You can easily explore the different groups and sections from there.
Next, we can inspect the Apex class from the code above. As you see, we have all the information needed.
Methods are described too.
In the Triggers section, you can examine the Apex triggers. They don’t require additional comments and provide only general info about conditions and the object.
There is also data about custom objects and fields in the documentation, description and type included.
Plus, standard Salesforce types in your documentation have links to the official Salesforce documentation for developers.
Conclusion
My final thoughts after trying IcApexDoc: it is a convenient tool for automated, quick, and accurate generation of Apex documentation. I recommend using it, especially if you are working in a free IDE without complex plugins for code description.
