34

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

13

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

  • I guess I could try improving the parser of ApexDoc -- it was looking for * @tag instead of just @tag which caused problems. Maybe I should revisit and see if I can fix the things I don't like about it. I have just now tried Doxygen again, and will update my question with details of what isn't working. – tomlogic Aug 28 '12 at 21:59
13

I've made some improvements to ApexDoc. Check out the writeup here: http://scox67.blogspot.com/2013/08/sf-apexdoc.html.

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.

  • 1
    Hi welcome to the forum! Just a suggestion, perhaps you could put a little bit more detail here about what your sfapexdoc can do? As people won't necessarily follow the link. – Doug B Aug 28 '13 at 12:51
  • 1
    Great work Steve! – Andrew Fawcett Sep 3 '13 at 8:06
  • Update: version 1.2.0 now includes parsing of nested classes. – Steve Cox Dec 17 '13 at 4:08
  • 1
    This is great, Steve - keep it up! – Ray Jan 3 '14 at 14:51
4

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

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

3

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.

enter image description here

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.