Documenting Web Services

The web services you build may include documentation for the web service. The documentation you include is displayed in WebLogic Workshop's Test View during web service testing.

# Documentation Content

The sections below describe the format and use of Javadoc comments in web services. The comments you include in your web services are included in the WSDL that you generate for each web service if you want to publish your web service for use by others. The documentation you provide will also be displayed on WebLogic Workshop's Service View, which is a production mode view that presents only the Overview Page you see in Test View.

When you write comments for web services, remember that a core concept of web services is platform- and language-independence. In WebLogic Workshop, you write web services in Java. But clients of you web services do not (and should not) need to know that. The descriptions you provide should explain the semantics of your web service and its methods and, at a high level, the XML and/or SOAP message formats your web service expects (the WSDL file specifies the details of message formats). Your descriptions should not include implementation details of your web service or mention Java data structures, classes or language features.

# Javadoc Comments

The documentation for your web service and its methods is optionally placed in Javadoc comments on the web service's main class and on each of its methods. These areas are described in more detail below.

Javadoc comments always begin with /** (not /*) and end with */. If you create a comment that begins with anything other than /**, it will not be considered a Javadoc comment and the information in this section will not apply.

## HTML Formatting in Comments

Javadoc comments may include HTML formatting tags. Some tools, including WebLogic Workshop's Test View, will honor the HTML formatting when presenting the documentation. This means you may include bolding (<b> tag), italics (<i> tag), lists (<ul> and <ol> tags with member <li> tags), etc.

## Javadoc Tags and Comment Structure

If Javadoc tags (tokens beginning with @) are present in a comment, they must be located at the end of the comment. Any text following a Javadoc tag (and preceding another tag) is considered arguments to the tag. If you include additional commentary after the Javadoc tags in a Javadoc comment, the WebLogic Workshop compiler will generate errors about inappropriate arguments to tags.

For example, the following Javadoc comments will compile successfully:

    /**
     * Credit reporting service.  This service simulates constructing
     * a credit report from multiple secondary sources of information.
     * It uses two external services, one representing a bank and the
     * other representing the Internal Revenue Service (IRS).

     *
     * The @jws:conversation-lifetime max-idle-time tag controls how
     * long a conversational instance of this service will survive without
     * seeing activity.

     *
     * Conversations represent resources: they shouldn't be left around.

     *
     * @jws:conversation-lifetime max-idle-time="30 minutes"
     */
    public class CreditReport
    {
        ...
    }

The following comment will not compile successfully because of the spurious comments following the @jws:conversation-lifetime tag.

    /**
     * Credit reporting service.  This service simulates constructing
     * a credit report from multiple secondary sources of information.
     * It uses two external services, one representing a bank and the
     * other representing the Internal Revenue Service (IRS).
     *
     * The @jws:conversation-lifetime max-idle-time tag controls how
     * long a conversational instance of this service will survive without
     * seeing activity.
     *
     * Conversations represent resources: they shouldn't be left around.
     *
     * @jws:conversation-lifetime max-idle-time="30 minutes"
     *
     * Here are some more comments that will cause compile problems.
     */
    public class CreditReport
    {
        ...
    }

These examples also illustrate the issue of mentioning Javadoc tags within comments. Notice that the comment discusses the @jws:conversation-lifetime tag. If the tag were located at the start of the line, it would be interpreted as a tag (not as a comment) and would generate compile errors because of the text following it. The presence of text before the comment on the line (the word "The") prevents the tag form being interpreted as an active tag.

## Class Comment

A Javadoc comment that immediately precedes a class is called the class comment. The class comment is currently not displayed in Test View, but it is included in WSDL files generated from a JWS file.

## Method Comment

A Javadoc comment that immediately precedes a class is called the method comment. Test View will display the method comment for each method on both the Overview Page and preceding the method parameters and invocation on the Test Form and Test XML pages.

Method comments are also included in WSDL files generated from a JWS file.

Related Topics

Introduction to Java

Structure of a JWS File

JWS Files: Java Web Services

WSDL Files: Web Service Descriptions