[SalesForce] Documenting Salesforce.com Apex class files

[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.

Best Answer

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

Related Topic