Documenting Web Services

The web services you build can 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 a web service are included in the WSDL that is generated for that web service. 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 topic 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 bold text (<b> tag), italics (<i> tag), lists (<ul> and <ol> tags with member <li> tags), etc.

Javadoc Annotations and Comment Structure

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

For example, the following Javadoc comments 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 attribute 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 attribute 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 annotations within comments. Notice that the comment discusses the @jws:conversation-lifetime annotation. If the annotation were located at the start of the line, it would be interpreted as an annotation (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 annotation form being interpreted as an active annotation.

Class Comment

A Javadoc comment that immediately precedes a class is called the class comment. Test View will display the class comment on the Overview Page.

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

Method Comment

A Javadoc comment that immediately precedes a method 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 the WSDL file generated from a JWS file.

Related Topics

Introduction to Java

Structure of a JWS File

WSDL Files: Web Service Descriptions