Documenting Salesforce.com Apex class files

Question

[I asked this question on Stack Overflow but didn't get any answers there.]

Since the Salesforce.com Apex language is "Java-like", I'd like to use javadoc or Doxygen to generate API documentation for the package we plan to release on App Exchange.

I found an ApexDoc project on Google Code, but it's severely limited and uses a naive parser to generate HTML output. I'd much rather take advantage of the existing Doxygen parsers and output generators than try to reinvent that wheel from scratch.

So, my questions:

1) Has anyone been able to use javadoc or Doxygen to generate API documentation for their Apex classes? How were you able to do it?

2) I'm wondering how hard it would be to write a simple script to create a series of .java files from the .cls Apex class files, adding fake import statements and possibly modifying certain declarations to keep Doxygen happy. Any thoughts on what Doxygen (or javadoc) is choking on when it tries to parse an Apex .cls file?

3) How do you maintain API documentation for your managed packages?

I'm amazed that Salesforce doesn't provide such a tool or hasn't contributed an Apex parser to javadoc/Doxygen. Their documentation and developer tools are extensive, and they've got a great automated test setup. I haven't found anything from them for auto generating documentation.

Additional Doxygen info:

I've re-run Doxygen, after configuring it for the src directory and to process *.cls files. Here's a list of problems I've run into:

• I have two classes that extend a virtual class, but they don't appear in the class list. The description of the virtual class includes the documentation for that class and the two others that extend it.

• Doxygen has trouble parsing the classes -- in one file, only three items show up, and none of the methods appear.

  • A class called Exception (I have two classes extending exception, but their documentation and names do not appear).
  • Two classes uses as the equivalent of C structures.

• It doesn't like the @isTest markup in our unit tests, but I should just be excluding those from the list of processed files.

Is Doxygen having trouble identifying the data types of return values and parameters? It must be more than that, because it wouldn't even document a public void Test( ) with a /** @brief Test */ comment block.

My problems with ApexDoc:

• Can't handle nested classes.
• Only handles javadoc tags in the form * @description instead of just @description. It should strip the leading whitespace and possible asterisk of each comment line before processing.
• Only processes @description, @author, @date, @return and @param tags.
• As far as I can tell from looking at the source, only supports multiple lines with @description, but not the other tags.
• Doesn't support /// or //< comments.
• Doesn't provide formatting like Doxygen (e.g., parameter list with one column for parameter name, and another column for its description).

Granted, ApexDoc is Open Source and I could try to address those problems, but I'm not a Java Developer. I see that there's a command-line interface I can probably use for testing/development, but I'm not all fired up to learn that platform, while still learning the Salesforce platform.

Answer 1

I have used apexDoc for a while and we are starting to roll it out more fully for our use at my organisation. It is open source software and so you could always contribute some updates for it :-) What features are you wanting to add to it that it doesn't have (just to give a flavour)?

In answer to your questions

1) I don't think anybody has successfully managed to do this. There is an idea of the ideas exchange for it to be done but it seems to gain very little support.

2) Theoretically it should be pretty easy as apex is a Java DSL. Have you tried running Doxygen and if so what errors does it throw up?

3) I use ApexDoc to generate some basic output and then have a little script tied in to copy across custom css and things. It isn't perfect but it does for the small amount we need at the moment.

I believe the IDE is being open sourced at some time in which case I would imagine the antlr grammar file would become available which may help you out.

I know it is not really an answer for what you wanted to hear per se, but sadly it's all we have atm (and I would love a nicer documentation generator!!)

Paul

Answer 2

I've made some improvements to ApexDoc. Check out the writeup here: https://lucidwaresolutions.com/sfapexdoc/

In a nutshell, SfApexDoc:

1. Parses javadoc-style comments and creates HTML documentation
2. recognizes standard tags such as @description, @author, @date, @return, @param, @see.
3. creates links to standard Apex types as well as your own classes
4. includes full class, method, and property signatures - even those that span multiple lines.

I'm actively working on fixing issues and adding features, so please send me a note if you find problems.

Answer 3

This question is quite old now, but in case anyone stumbles upon it, since most SF development has moved to VS Code, I ported the original ApexDoc over to TypeScript and made several major improvements. It is very easy to document your class files in VS Code (comment blocks can be contextually stubbed, automatically filling in your method params), and preview your docs in seconds. Check it out here: https://marketplace.visualstudio.com/items?itemName=PeterWeinberg.apexdox-vs-code&ssr=false

Hope someone finds this useful!

Answer 4

Long before the Force.com Tooling API came out I tried to buid a native tool in Salesforce to render UML class diagrams for Apex classes and SObjects.

The extraction of the class and object information is solely done in Apex. I really had to use very ugly RegExp parsing of classes to get out relationships, fields and object.

This definitly runs into limits or errors if you classes are too complex. So regard this as a proof of concept and...

Feel free to check (fork and collaborate) it on GitHub: https://github.com/rsoesemann/plantuml4force

Answer 5

I'm using Apexdoc and it's quite good. You can integrate it in Eclipse now.

• Download the .jar here http://code.google.com/p/apexdoc/downloads/list

• copy and paste it in your Eclipse folder : /Applications/Eclipse/plugins

• Restart Eclipse

• Right click on a project > Force.com > Generate Doc

For more information, here is the sources :

http://techsahre.blogspot.com.au/2011/01/apexdoc-salesforce-code-documentation.html http://techsahre.blogspot.com.au/2011/02/apexdoc-eclipse-plugin-for-forcecom-ide.html

Answer 6

Adding another option that is also a re-purposing of ApexDoc and making it easier to use. Cesar Parra created this Nodes.js library hosted on npm based on ApexDocs that provides CLI capabilities.

In particular, it generates a markdown file per Apex class being documented. As he says,

This means you can host your files in static web hosting services that parse Markdown like Github Pages or Netlify, and use site generators like Jekyll or Gatsby. This gives you the freedom to decide how to style your site to match your needs.

You can also generate files that docsify can handle and serve up a local server to preview a site of your documentation.