Skip to main content

クラス・ドキュメントの作成

InterSystems IRIS® データ・プラットフォームには、インターシステムズ・クラス・リファレンスという Web ページが用意されています。このページには、インターシステムズが提供しているクラスと、ユーザが作成するクラスについて、自動的に生成されるリファレンス情報が表示されます。クラス・リファレンスは %CSP.DocumaticOpens in a new tab クラスによって生成されるため、非公式には Documatic とも呼ばれています。

URL の形式は以下のとおりです。<baseURL> はインスタンスのベース URL です。

https:<baseURL>/csp/documatic/%25CSP.Documatic.cls

この Web ページの外観は、オンラインのクラス・リファレンスとは異なっています (オンラインのクラス・リファレンスは残りのオンライン・ドキュメントとも接続されているため)。

クラス・リファレンスの概要

クラス・リファレンスの目的は、クラスの使用可能な部分と、その部分の使用方法をプログラマに公表することです。以下に例を示します。

このクラスに Age (整数) と DOB (日付) というプロパティがあることを示すクラス・リファレンスの抜粋。

このリファレンス情報には、クラス・メンバの定義が示されていますが、それらの実際の実装ではありません。例えば、メソッド・シグニチャが示されていますが、それらの内部定義ではありません。これには、要素間のリンクが含まれており、コードのロジックを迅速にたどることができます。また、検索オプションも用意されています。

クラス・リファレンスに含めるドキュメントの作成

クラス・リファレンスに含めるドキュメントを作成するには、クラス定義内にコメントを作成します。コメントは、/// で開始します。このようなコメントの付いたクラス宣言を前に置くと、そのコメントはクラスのページの最上位に示されます。このようなコメントの付いた特定のクラス・メンバを前に置くと、コメントは生成されたそのクラス・メンバの情報の後に示されます。クラスをコンパイルしておくと、次にクラス・リファレンス・ドキュメントを開いたときに、生成されたクラス・ドキュメントを表示できます。クラス・リファレンスのコメントを追加しない場合、クラスやパッケージに追加した項目は、そのクラスやパッケージの内容のリストに正しく表示されますが、それらを説明するテキストは表示されません。

クラス・リファレンスの既存のコメントは、クラス定義を変更することによって拡張できます。クラス・リファレンスのコメントの構文規則は以下のように厳密です。

  • クラス・リファレンスの中でクラスまたはクラス・メンバを説明するすべてのコメントは、そのコメントで説明している項目の宣言の直前に、連続するブロックとして記述する必要があります。

  • コメントのブロックを構成する各行の先頭には、3 つのスラッシュ (///) を記述します。

    Tip:

    既定では、この表示は、/// のすべての行のテキストをまとめ、その結果を 1 つの段落として扱うことに注意してください。HTML の改行 (<br>) を挿入できます。または、HTML フォーマット (<p>、</p> など) を使用できます。サブセクションを参照してください。

  • この 3 つのスラッシュは、行の先頭 (左端) に配置する必要があります。

  • クラス・リファレンスのコメントに空白行を入れることはできません。

  • クラス・リファレンスのコメントの最終行とそのコメントで説明している項目の宣言の間に空白行を入れることはできません。

  • クラス・リファレンスのコメントの長さ (すべての行の合計) は、文字列長の制限 (きわめて長い) 未満である必要があります。“文字列長の制限” を参照してください。

クラス・リファレンスのコメントには、プレーン・テキストのほか、あらゆる標準 HTML 要素および少数の専用要素を使用できます。

クラス・ドキュメントでの HTML マークアップの使用

クラスのコメントでは、HTML タグを使用できます。マークアップでは、可能な限り厳密な HTML 標準 (XHTML など) に従い、どのブラウザでも結果を表示できるようにしてください。%CSP.DocumaticOpens in a new tab クラスは完全な HTML ページを生成し、クラス・ドキュメントはそのページ上の <body> 要素の内部に格納されます。このため、HTML タグ <html>、<body>、<head>、または <meta> をマークアップに含めないでください。これらのタグはすべて無視されます。また、クラス名は <h1> の見出しとして表示されるため、見出しを使用する場合は <h2> 以下の見出しを使用してください。検索エンジンは <h1> が 1 つだけ含まれる HTML ページを優先するため、マークアップ内に <h1> を含めた場合、その見出しは <h2> に変換されます。

標準的な HTML のほかに、<CLASS>、<METHOD>、<PROPERTY>、<PARAMETER>、<QUERY>、および <EXAMPLE> の各タグも使用できます。(標準的な HTML タグと同様に、これらのタグの名前は大文字と小文字を区別しません。)最も一般的に使用するタグについては、ここで説明されています。その他の詳細は、%CSP.DocumaticOpens in a new tab のドキュメントを参照してください。

<CLASS>

クラス名をタグ付けします。クラスが存在する場合、コンテンツはクラスのドキュメントに対するリンクとして表示されます。以下に例を示します。

/// This uses the <CLASS>MyApp.MyClass</CLASS> class.
<EXAMPLE>

プログラム例をタグ付けします。このタグは、テキストの外観に影響します。それぞれの /// 行は、例の中で独立した行になります (行が単一の段落に結合される通常の場合とは対照的です)。以下に例を示します。

/// <EXAMPLE>
/// set o=..%New()
/// set o.MyProperty=42
/// set o.OtherProp="abc"
/// do o.WriteSummary()
/// </EXAMPLE>
<METHOD>

メソッド名をタグ付けします。メソッドが存在する場合、コンテンツはメソッドのドキュメントに対するリンクとして表示されます。以下に例を示します。

/// This is identical to the <METHOD>Unique</METHOD> method.
<PROPERTY>

プロパティ名をタグ付けします。プロパティが存在する場合、コンテンツはプロパティのドキュメントに対するリンクとして表示されます。以下に例を示します。

/// This uses the value of the <PROPERTY>State</PROPERTY> property.

これは、HTML マークアップを使用した複数行にわたる説明です。

/// The <METHOD>Factorial</METHOD> method returns the factorial
/// of the value specified by <VAR>x</VAR>.

関連項目

パッケージのオプションNext section
Previous sectionクラスのコンパイルと配置
FeedbackOpens in a new tab