Standardize Apex Documentation by Using "new" ApexDoc Comment Format in Winter '26 Release

October 11, 2025

In Winter ‘26 Salesforce introduced their own documentation format - Standardize Apex Documentation by Using the ApexDoc Comment Format

Why?

The first thing Salesforce mentions on the Release doc is

ApexDoc, a new standardized comment format, makes it easier for humans, documentation generators, and AI agents to understand your codebase.

While I believe that the tags that are mentioned in the documentation ( ApexDoc Comment Structure and Tags) will make understanding code better for their AI, but right now I see a huge problem mainly for Salesforce Developers and Consultants who will need to change their documentation comments (I will get to this point later).

What's new?

Not much actually. Salesforce put ApexDoc as part of their own documentation ( Document Your Apex Code), added a few tags, and called it Standardize Apex Documentation. The ApexDoc was introduced by Aslam Bari, and later it was transformed into https://github.com/SalesforceFoundation/ApexDoc. There are other tools that allow generating documentation both free and paid.

Having multiple @author tags

Multiple @author tags is great for a consultant like me, who works with multiple customers, where other Consultants or Developers did some work and put their names in the documentation.

/**
*
* @author Andrii Muzychuk
* @author John Dou
*
*/
public interface IContentDocumentLinkSelector {
   ContentDocumentLink selectByLinkedEntityIdAndFileName(Id linedEntityId, String fileName);
}

The @example tag

The @example tag is cool. Personally, I will use this feature. I like the way Salesforce allows us to put code examples in the comments

/**
*
* @author Andrii Muzychuk
* @author John Dou
*
* @example
* {@code
*
*    private static List newContentVersions;
*
*    static {
*        newContentVersions = (List)Trigger.new;
*    }
*
*    private static IContentVersionSelector contentVersionSelector;
*
*    @TestVisible
*    private static void setContentVersionSelector(IContentVersionSelector overideContentVersionSelector) {
*        if (contentVersionSelector != null) {
*            contentVersionSelector = overideContentVersionSelector;
*        }
*    }
*
*    private static IContentVersionSelector getContentVersionSelector() {
*        if (contentVersionSelector == null) {
*            contentVersionSelector = new ContentVersionSelector();
*        }
*        return contentVersionSelector;
*    }
*
*    public static void afterUpdate() {
*        for (ContentVersion cvItem : getContentVersionSelector().selectByRecords(newContentVersions)) {
*            // process attachment
*        }
*    }
*
* }
*/
public class ContentVersionSelector implements IContentVersionSelector {
   public List selectByRecords(List contentVersionRecords) {
       return contentVersionRecords;
   }
}

@since tag

As a consultant with multiple customers I love @since tag. It allows you to put a date when something was done in relation to a code for which the comment is applied. While some people consider @since and @version as a bad practice, personally I feel this tag will help my customers who don’t use any source control like GitHub to identify when and who made a change.

@description tag

Oh no… there is no @description tag.

The main description is the first block of text within an ApexDoc comment. It doesn’t have an explicit tag.

Yes, Salesforce copied relevant tags from JavaDoc, which does not have a dedicated @description tag. And this one is super questionable! While all the Apex code document formats have @description tag, Salesforce decided to have description of a comment without any tag. Super weird way to standardize documentation. Like for everything you have tags but for this one let’s make an exception. This one will make Developers and Consultants suffer - they will need to move their descriptions to the top of the comment section and remove @description tag. Who will pay for hours of super intellectual copy/paste activity… or maybe we can use AI to do this?

What’s next?

There are two options:
There is no mention of a document generation tool. So… Salesforce’s ApexDoc is just for the Salesforce benefit not for their customers. Yes, maybe AI will help somehow utilize this new format, we’ll see. External services will need to incorporate new tags and the absence of @description tag. Developers and Consultants will need to spend some time to change the comments too. Salesforce creates additional work for everyone. Thank you!