Web サービスのコメントを記述する
構築した Web サービスには、その Web サービスのドキュメントを含めることができます。そのドキュメントは、Web サービスのテスト時には WebLogic Workshop のテスト ビューに表示されます。
以下の節では、Web サービスでの Javadoc コメントのフォーマットと使い方について説明します。Web サービスに含めるコメントは、Web サービスを他者が使用できるように公開する場合には Web サービスごとに生成する WSDL に配置します。提供するドキュメントは、WebLogic Workshop のサービス ビューにも表示されます。サービス ビューは、テスト ビューで表示される ［Overview］ ページのみを示すプロダクション モード ビューです。
Web サービスのコメントを記述するときには、Web サービスの中心的なコンセプトが「プラットフォームおよび言語に依存しない」であることを忘れないでください。WebLogic Workshop では、Web サービスを Java で記述します。ただし、Web サービスのクライアントはそのことを知っている必要はありません。提供するドキュメントでは、Web サービスとそのメソッドのセマンティクス、および Web サービスが対応する XML/SOAP メッセージのフォーマットを説明する必要があります（メッセージ フォーマットの詳細は WSDL ファイルで規定）。Web サービスの実装の詳細を説明したり、Java のデータ構造、クラス、または言語の特徴について言及したりしないようにします。
Web サービスとそのメソッドのドキュメントは、必要に応じて、Web サービスのメイン クラスおよび各メソッドの Javadoc コメントに配置します。それらの領域については、以降に詳しく説明します。
Javadoc コメントは常に /**（/* ではない)で始まり、*/ で終わります。/** 以外で始まるコメントを作成した場合、それは Javadoc コメントとは見なされず、この節の情報は意味をなしません。
Javadoc コメントでは、HTML フォーマッティング タグを使用できます。WebLogic Workshop のテスト ビューなどの一部のツールでは、ドキュメントを表示するときに HTML フォーマッティングが尊重されます。つまり、太字（<b> タグ）、斜体（<i> タグ）、リスト（<ul>、<ol>、および <li> タグ）などを使用することができます。
Javadoc タグ（@ で始まるトークン）がコメントに存在する場合、それらのタグはコメントの最後に配置される必要があります。Javadoc タグから別のタグまでのテキストはすべてそのタグの引数と見なされます。Javadoc コメントで Javadoc タグの後に注釈を追加すると、タグの引数が不適切であることを理由に WebLogic Workshop コンパイラがエラーを生成します。
たとえば、次の Javadoc コメントは正常にコンパイルされます。
/** * 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 { ... }
次のコメントは、@jws:conversation-lifetime タグの後に不適切なコメントがあるため正常にコンパイルされません。
/**
* 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
{
...
}
以上の例は、コメント内で Javadoc タグに言及するという問題も示しています。コメントの中で @jws:conversation-lifetime タグについて説明されています。このタグが行の先頭に配置されていたら、それは（コメントではなく）タグとして解釈され、それに続くテキストが原因でコンパイル エラーが発生します。「The」というテキストが先頭にあることで、タグがアクティブなタグとして解釈されないようになっています。
クラスの直前の Javadoc コメントは、クラス コメントと呼ばれます。クラス コメントは現時点ではテスト ビューに表示されませんが、JWS ファイルから生成された WSDL ファイルに配置されます。
メソッドの直前の Javadoc コメントは、メソッド コメントと呼ばれます。テスト ビューは、［Overview］ ページで、および ［Test Form］ ページと ［Test XML］ ページのメソッドのパラメータおよび呼び出しの前に各メソッドのメソッド コメントを表示します。
メソッド コメントも JWS ファイルから生成された WSDL ファイルに配置されます。