This discussion is archived
10 Replies Latest reply: Sep 19, 2010 7:45 PM by 843810 RSS

Can Javadoc be used to document a Web Services API?

843810 Newbie
Currently Being Moderated
Can Javadoc be used to document a Web Services API? Are there special tags or doclets suited for this task? If not, what tools are being used to write Javadoc-like documentation for Web Services APIs?
  • 1. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Hi,

    We're developing a web services doclet at Google that generates API docs for SOAP-based APIs represented in Java. Here are two documents generated by it:

    AdWords API
    http://www.google.com/apis/adwords/developer/AdGroup.html

    AdSense API
    http://code.google.com/apis/adsense/developer/index.html

    Is this close to what you're looking for?

    Basically, the web service is implemented in Java. The doc comments are in those source files; our doclet generates the pages shown above. This reference serves client libraries in Java, Python, PHP, Perl, C# and others. This doclet is a modification of the standard doclet.

    The special tags we developed are not specific to SOAP, but are specific to our implementation -- a specific way to handle enums and annotations (for versioning and implementations of interfaces or abstract classes).

    It does not rely on or make use of the service's WSDL file.

    The doclet has conventions for marking source with annotations for versioning (e.g., a method is available over a range, from v2 to v9), so you can publish a document that contains multiple versions and diff against them. You can see the diffs in the first document above by clicking in the upper right corner, first on V11, then on V9 below it)

    We would like to make this doclet available as open source, but need to learn the open source licensing terms for the standard doclet (is it open source?).

    -Doug
  • 2. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Yes, this is very close to what we're looking for at Egenera, and the versioning is a nice bonus. Is the versioning flexible enough that it could be used to delineate platform-specific information (platform x vs. platform y)?

    I'm also curious if you use exclusions to control what methods get published? Our web service API is a subset of the Java implementation, and the file structure is different from the typical Javadoc treatment. The classes and methods are in separate files, but there is a file that is a concatenation of all the published methods that feeds into the WSDL. We need the web services documentation to reflect the published API, not the entire Java implementation of it.

    Do you know if there are any tools that do make use of the WSDL? I noticed that VMware has some web service API doc, and each message/type description had a nifty link that displays the WSDL definition of that single object.

    If Google can make the doclet available as open source, what would the lead time be? We're looking for a solution in the next month or so.

    Thanks very much for your reply,
    Mary Beth
  • 3. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Yes, the version annotation has "from" and "to" elements:

    @Available(from=Version.v2, to=Version.v3)
         for specifying version of a public class, interface, enum, constructor, method or field

    It also has an "access" element for distinguishing different targets, such as "normal", "internal", "oem", etc. You could probably use this for platforms.

    @Available(in=Access.normal)
    for specifying user access of a public class, interface, enum, constructor, method or field

    Of course, the documentation must reflect the WSDL and not the implementation. We do have an exclusion annotation:

    @DoNotDocument
    apply to public class, interface, enum, method or field that you do not want documented as part of the public API

    These annotations are all used when generating both the docs and the WSDL.
    Don't know that much about other tools, and how they use the WSDL.

    Where is the VMWare page you're referring to? Somewhere around here?
    http://pubs.vmware.com/labmanager25/wwhelp/wwhimpl/js/html/wwhelp.htm

    We've spent about 1.5 years of development on this doclet, so it's pretty robust. Just don't know how long it would take to publish. Sincerely doubt if it could be done within a month or two.

    -Doug
  • 4. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Thanks for answering my questions. I hope you can publish the doclet as open source because it sounds very useful.

    Here is the link to the VMware doc. If you paw around, you'll see the "Show WSDL Definition" links in the object descriptions.
    http://pubs.vmware.com/vi301/sdk/ReferenceGuide/index.html

    Mary Beth
  • 5. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Hi,

    Your discussion became so interesting that I decided to join :)
    Do you know if there are any tools that do make use of the WSDL? I noticed that VMware has some web service API doc, and each message/type description had a nifty link that displays the WSDL definition of that single object.
    We actually are working on this right now.

    Here, some guys have already heard about a tool called DocFlex/Javadoc:

    http://www.filigris.com/products/docflex_javadoc/

    (and are probably tired of hearing about it :-) This is a template-driven doclet. More exactly, a tool for rapid development of Javadoc doclets.

    But we actually have another tool based on the same technology. It is called DocFlex/XML and uses any XML files as a data source (unlike the Doclet API, in case of DocFlex/Javadoc). For more details, see:

    http://www.filigris.com/products/docflex_xml/

    Using DocFlex/XML, we have already developed a set of templates called "XSDDoc":

    http://www.filigris.com/products/docflex_xml/xsddoc/

    It works as an excellent quality XML schema documentation generator (both in the form of Javadoc-like framed HTML and RTF). You can see a documentation generated with it by this link:

    http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/

    Our next goal is to extend that template set to be able to generate WSDL documentation. This will be called "WSDLDoc". It will document both WSDL files and XML schemas embedded into them.

    The "WSDLDoc" template set (that is, a full-blown WSDL documentation generator) is planned for release somewhere during Q1 2008. We are a little company and need to do lots of various things in order to survive, but we will definitely release such a doc-generator because the demand is obvious and our technology is currently rife enough to develop this extremely fast. It won't be open source, but it will work in two mode: fully-featured commercial and limited freeware.

    I will let know here when our WSDLDoc is finished.

    Best regards,
    Leonid Rudy
    http://www.docflex.com
  • 6. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Sounds great, Leonid. I look forward to seeing WSDLDoc.

    -Doug
  • 7. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Doug, Leonid,
    how far are you with the publishing of your tools? They seem to be exactly what I need now, are there any news yet?
    Regards, Johannes
  • 8. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Hi,

    We are still working on this now and will finish it definitely.

    But the delivery time is delayed. Mainly because we have lots of other things to do.
    You guys will pay your money only for pretty much working stuff.
    Meanwhile, first, someone has to finance developing this.
    That's what we also have to do! (We don't have a Microsoft or Google behind us :)

    I estimate now that our WSDLDoc (with the full support of XML schemas embedded into WSDL)
    will be released somewhere during the frame of 2008.

    Best regards,
    Leonid Rudy

    http://www.docflex.com
  • 9. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    Doug,
    has there been any release of the tool you were talking about here?

    I think there is a need for such a tool and would love to see it happen.

    Kaj
  • 10. Re: Can Javadoc be used to document a Web Services API?
    843810 Newbie
    Currently Being Moderated
    this tool may do the job:

    http://www.adivo.com/