[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.
- A class called
It doesn't like the
@isTestmarkup 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
* @descriptioninstead 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
- 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.