ABAP コードへの文書の追加

ABAP コードの文書化

Objective

After completing this lesson, you will be able to aBAP コードを文書化します。

ABAP コード文書

クラス、メソッド、またはタイプの名称にカーソルを合わせ、F2 を押すと、対応するエレメント情報を含むダイアログウィンドウが表示されます。

ABAP Doc を使用して、このダイアログに文書を追加することができます。この文書を登録するには、コードに特別なコメント行を追加します。ABAP Doc では、以下の宣言命令を文書化することができます。

  • CLASS
  • INTERFACE
  • METHODS
  • TYPES
  • DATA
  • CONSTANTS

メソッドおよび汎用モジュールの個別パラメータおよび例外を文書化することもできます。

ABAP Doc コメントは、文書化されるエレメントの前に置かれます。これらは、文字 "! で始まります。許可されていないクラスの位置で ABAP Doc を登録しようとすると、構文警告が表示され、文書は無視されます。

ABAP Doc コメントは翻訳できません。そのため、どの言語で文書を登録するかを慎重に検討する必要があります。

ABAP Doc コメントがエレメント文書の一部になります。

ABAP Doc では、HTML タグのサブセットを使用して、文書を書式設定することができます。この例では、強調に <strong> タグ、改行に <br> タグを使用しています。(改行タグがないと、ABAP Doc の 2 行が隣り合って表示されることに注意してください)。

強調されたテキストと改行に加えて、以下のタグを使用することができます。

ABAP Doc の追加書式タグ

目的書式設定タグ
ヘッダ、レベル 1<h1>...</h1>
ヘッダ、レベル 2<h2>...</h2>
ヘッダ、レベル 3<h3>...</h3>
強調テキスト<em>...</em>
段落<p>...</p>
未ソート一覧<ul><li>...</li>...<li>...</li></ul>
ソート一覧<ol><li>...</li>...<li>...</li></ol>

ヒント

ABAP Doc コメント内では、コード完了 (Ctrl + Space) を使用して書式設定タグを挿入することができます。

ABAP Doc では、メソッドとその個別パラメータの両方を文書化することができます。メソッドを文書化するには、通常の "! コメントを使用します。パラメータを文書化するには、"! @parameter <name> | という表記を使用し、パイプ文字 (|) の後にコメントを追加します。

クイックフィックスを使用して、メソッドとその署名に ABAP Doc を追加することができます。メソッドを宣言したら、Ctrl + 1 を押して可能なクイックフィックスを開き、Add ABAP Doc を選択します。その後、エディタによって対応する文書が生成されます。

メソッドの署名が変更された場合は、クイックフィックスを使用して、削除されたパラメータの ABAP Doc コメントを削除し、新しいパラメータの ABAP Doc コメントを追加することができます。

オブジェクトの ABAP Doc 説明が、オブジェクトプロパティおよびオブジェクト一覧の説明で複製されるようにすることができます。これを行うには、class="shorttext synchronized" オプションで段落タグ <p> を使用します。

オブジェクトプロパティの説明に加えた変更は、ABAP Doc コメントに複製されます。

他のオブジェクトの文書にナビゲーションリンクを追加することができます。

オブジェクト全体にリンクするだけでなく、個々の要素にリンクすることもできます。この例では、メソッド GET_AIRPORTS へのリンクがあります。- リンク "! {@link zif_1_abap_doc_constants.DATA:auth_create} により、インタフェース ZIF_1_ABAP_DOC_CONSTANTS の定数 auth_create の文書へのリンクが定義されます。

個々のエレメントには、以下の ID を使用します。

データ
適切なコンテキストの定数、変数、およびプロシージャパラメータの場合
道間
ABAP ディクショナリのドメイン
INTF
クラスに実装されているインタフェース (インタフェースコンポーネントへのアクセスに使用)
METH
メソッド

ABAP Doc を使用してコードを文書化する方法

ABAP 文書を使用してコードを文書化する方法については、このビデオを視聴してください。

ABAP コードへの文書の追加

この演習問題では、操作を容易にするために、コーディングに文書を追加します。

テンプレート:

  • /LRN/CL_S4D401_EXS_CLASS (グローバルクラス)

ソリューション:

  • /LRN/CL_S4D401_DCS_ABAP_DOC (グローバルクラス)

タスク 1: テンプレートのコピー (オプション)

テンプレートクラス /LRN/CL_S4D401_EXS_CLASS をコピーします。前の演習問題を完了した場合は、このタスクをスキップし、クラス ZCL_##_SOLUTION の編集を続行することができます。

ステップ

  1. クラス /LRN/CL_S4D401_EXS_CLASS を独自のパッケージのクラスにコピーします (推奨名: ZCL_##_SOLUTION、## はグループ番号)。

    1. Project Explorer で、クラス /LRN/CL_S4D401_EXS_CLASS を右クリックしてコンテキストメニューを開きます。

    2. コンテキストメニューから Duplicate.... を選択します。

    3. Package 項目にパッケージの名称を入力します。Name 項目に、ZCL_##_SOLUTION (## はグループ番号) と入力します。

    4. Next を選択します。

    5. 移送依頼を確認し、Finish を選択します。

  2. コピーを有効化します。

    1. Ctrl + F3 を押してクラスを有効化します。

タスク 2: 文書追加

ABAP Doc 文書をローカルクラス LCL_CARRIER およびファクトリメソッド GET_INSTANCE に追加します。

提案された文書テキスト

タイプコードエレメントアクティビティ
ローカルクラスLCL_CARRIER

フライトキャリア - 工場ロジックにより、航空会社 ID ごとに 1 つのインスタンスのみが存在することが保証されます。

MethodGET_INSTANCE

ファクトリメソッド - このクラスのインスタンスを返します。

パラメータi_carrier_id

運送業者の 3 文字の ID。

パラメータr_resultインスタンスへの参照 - インスタンス化が失敗した場合は初期値。
例外ZCX_##_FAILEDインスタンス化失敗 - 詳細については例外テキストを評価してください。

ステップ

  1. クイックフィックスを使用して、ABAP Doc 文書をローカルクラス LCL_CARRIER に追加します。

    1. グローバルクラスで、ローカルクラス LCL_CARRIER の定義にナビゲートします。

    2. CLASS … DEFINITION 命令で、lcl_carrier にカーソルを置き、Ctrl + 1 を押して利用可能なクイックフィックスを呼び出します。

    3. 利用可能なクイックフィックスの一覧から、Add ABAP Doc を選択します。

      結果

      クイックフィックスにより、コードが以下のように調整されます。
      ABAP
      12
        "! 
  CLASS lcl_carrier DEFINITION CREATE PRIVATE.

  2. 表のテキストを使用して文書を更新します。

    ヒント

    Enter を押すと、エディタによって "! で始まる新しい行が挿入されます。

    1. コードを以下のように調整します。

      ABAP
      123
        "! Flight Carrier -
  "! A factory logic ensures that there can only be one instance for each carrier ID. 
  CLASS lcl_carrier DEFINITION CREATE PRIVATE.

  3. ローカルクラス LCL_CARRIER の ABAP エレメント情報を照会して、出力を確認します。

    1. CLASS … DEFINITION 命令で、lcl_carrier にカーソルを置き、F2 を押してエレメント情報を表示します。

    2. ABAP Doc テキストがヘッダ Documentation の下に表示されます。

  4. クイックフィックスを使用して、ローカルクラス LCL_CARRIER の静的メソッド GET_INSTANCE に ABAP Doc 文書を追加します。

    1. LCL_CARRIER クラスで、メソッド GET_INSTANCE の定義にナビゲートします。

    2. CLASS-METHODS 命令で、get_instance にカーソルを置き、Ctrl + 1 を押して利用可能なクイックフィックスを呼び出します。

    3. 利用可能なクイックフィックスの一覧から、Add ABAP Doc を選択します。

      結果

      クイックフィックスにより、コードが以下のように調整されます。
      ABAP
      12345
        "! 
  "! @parameter i_carrier_id |
  "! @parameter r_result |
  "! @raising zcx_##_failed |  
  CLASS-METHODS get_instance

  5. 表のテキストを使用して、メソッドの文書を更新します。

    1. コードを以下のように調整します。

      ABAP
      12345
        "! Factory method - returns an instance of this class.
  "! @parameter i_carrier_id |
  "! @parameter r_result |
  "! @raising zcx_##_failed |
  CLASS-METHODS get_instance

  6. メソッドパラメータおよび例外の文書を、表のテキストで更新します。

    1. コードを以下のように調整します。

      ABAP
      12345
        "! Factory method - returns an instance of this class.
  "! @parameter i_carrier_id | Three-character identification of the carrier.
  "! @parameter r_result | Reference to the instance - initial if instantiation failed.
  "! @raising zcx_##_failed | Instantiation failed - evaluate the exception text for details.
  CLASS-METHODS get_instance

  7. ローカルクラス LCL_CARRIER のメソッド GET_INSTANCE の ABAP エレメント情報を照会して、出力を確認します。

    1. CLASS-METHODS 命令で、get_instance にカーソルを置き、F2 を押してエレメント情報を表示します。

    2. ABAP Doc テキストは、ヘッダ Documentation の下に表示されます。

タスク 3: 書式設定済文書の追加

ローカルクラス LCL_CARRIER のメソッド FIND_PASSENGER_FLIGHT の書式設定済 ABAP Doc 文書を追加します。オプションで、メソッド FIND_CARGO_FLIGHT に類似の ABAP Doc 文書を追加します。

提案された文書テキスト

タイプコードエレメントアクティビティ
MethodFIND_PASSENGER_FLIGHT

2 つの空港間の旅客便を検索します。

  • 特定の日付以降であり、
  • には最少残り空席があります
パラメータi_airport_from_id

出発空港

パラメータi_airport_to_id到着空港
パラメータi_from_date最初の可能フライト日付
パラメータi_sets空席の最小数
パラメータe_flightフライトが見つかりました (オブジェクト参照)
パラメータ_days_later要求日付後の日数

ステップ

  1. クイックフィックスを使用して、ABAP Doc 文書をローカルクラス LCL_CARRIER のメソッド FIND_PASSENGER_FLIGHT に追加します。

    1. LCL_CARRIER クラスで、メソッド FIND_PASSENGER_FLIGHT の定義にナビゲートします。

    2. METHODS 命令で、find_passenger_flight にカーソルを置き、Ctrl + 1 を押して利用可能なクイックフィックスを呼び出します。

    3. 利用可能なクイックフィックスの一覧から、Add ABAP Doc を選択します。

      結果

      クイックフィックスにより、コードが以下のように調整されます。
      ABAP
      12345678
        "! 
  "! @parameter i_airport_from_id |
  "! @parameter i_airport_to_id |
  "! @parameter i_from_date |
  "! @parameter i_seats |
  "! @parameter e_flight |
  "! @parameter e_days_later |
  METHODS find_passenger_flight

  2. 表のテキストを使用して、メソッドの文書を更新します。乗客のフライトを強調されたテキストとして書式設定し、フライトプロパティにソートされていない一覧を使用してください。

    ヒント

    書式ディレクティブを暗記する必要はありません。Ctrl + Space を押して、コード完了によって書式ディレクティブを挿入します。

    1. コードを以下のように調整します。

      ABAP
      123456789101112
        "! Search for a <strong>passenger flight</strong> between two airports that
  "! <ul>
  "! <li>lies on or after a given date and</li>
  "! <li>has a minimum number of available seats left</li>
  "! </ul>
  "! @parameter i_airport_from_id |
  "! @parameter i_airport_to_id |
  "! @parameter i_from_date |
  "! @parameter i_seats |
  "! @parameter e_flight |
  "! @parameter e_days_later |
  METHODS find_passenger_flight

  3. 表のテキストを使用して、メソッドパラメータの文書を更新します。出発および到着は、強調テキストとして書式設定してください。

    1. コードを以下のように調整します。

      ABAP
      123456789101112
        "! Search for a <strong>passenger flight</strong> between two airports that
  "! <ul>
  "! <li>lies on or after a given date and</li>
  "! <li>has a minimum number of available seats left</li>
  "! </ul>
  "! @parameter i_airport_from_id | <em>Departure</em> airport
  "! @parameter i_airport_to_id | <em>Arrival</em> airport
  "! @parameter i_from_date | First possible flight date
  "! @parameter i_seats | Minimum number of available seats
  "! @parameter e_flight | Found flight (object reference)
  "! @parameter e_days_later | Number of days after the requested date
  METHODS find_passenger_flight

  4. ローカルクラス LCL_CARRIER のメソッド FIND_PASSENGER_FLIGHT の ABAP エレメント情報を照会して、出力を確認します。

    1. METHODS 命令で、find_passenger_flight にカーソルを置き、F2 を押してエレメント情報を表示します。

    2. ABAP Doc テキストは、ヘッダ Documentation の下に表示されます。

  5. オプション: メソッド FIND_CARGO_FLIGHT の同様の書式設定済 ABAP Doc 文書を追加します。

    ヒント

    メソッド FIND_PASSENGER_FLIGHT の ABAP Doc 文書をコピーしてペーストし、それをメソッド FIND_CARGO_FLIGHT に調整します。

    1. コードを以下のように調整します。

      ABAP
      123456789101112
        "! Search for a <strong>cargo flight</strong> between two airports that
  "! <ul>
  "! <li>lies on or after a given date and</li>
  "! <li>has a minimum number of available capacity left</li>
  "! </ul>
  "! @parameter i_airport_from_id | <em>Departure</em> airport
  "! @parameter i_airport_to_id | <em>Arrival</em> airport
  "! @parameter i_from_date | First possible flight date
  "! @parameter i_cargo | Minimum number of available capacity
  "! @parameter e_flight | Found flight (object reference)
  "! @parameter e_days_later | Number of days after the requested date
  METHODS find_cargo_flight

タスク 4: リンク追加

ローカルクラス LCL_FLIGHT に以下の ABAP Doc 文書を追加します。

提案された文書テキスト

タイプコードエレメントアクティビティ
ローカルクラスLCL_FLIGHT

クラス lcl_passenger_flight および lcl_cargo_flight の抽象スーパークラス

すべてのインスタンスは、属性 carrier_id、connection_id、および flight_date によって一意に識別されます。

ローカルサブクラス LCL_PASSENGER_FLIGHT および LCL_CARGO_FLIGHT の文書と、パブリック属性 carrier_id、connection_id、および flight_date へのリンクを追加します。

ステップ

  1. クイックフィックスを使用して、ABAP Doc 文書をローカルクラス LCL_FLIGHT に追加します。

    1. グローバルクラスで、ローカルクラス LCL_FLIGHT の定義にナビゲートします。

    2. CLASS … DEFINITION 命令で、lcl_flight にカーソルを置き、Ctrl + 1 を押して利用可能なクイックフィックスを呼び出します。

    3. 利用可能なクイックフィックスの一覧から、Add ABAP Doc を選択します。

      結果

      クイックフィックスにより、コードが以下のように調整されます。
      ABAP
      12
        "! 
  CLASS lcl_flight DEFINITION ABSTRACT.

  2. 表のテキストを使用して文書を更新します。

    1. コードを以下のように調整します。

      ABAP
      12345678
        "! Abstract superclass for classes 
  "! lcl_passenger_flight and 
  "! lcl_cargo_flight
  "! Every instance is uniquely identified by attributes
  "! carrier_id,
  "! connection_id, and
  "! flight_date.  
  CLASS lcl_flight DEFINITION ABSTRACT.

  3. lcl_cargo_flight の後に改行を追加します。

    1. コードを以下のように調整します。

      ABAP
      12345678
        "! Abstract superclass for classes 
  "! lcl_passenger_flight and 
  "! lcl_cargo_flight <br/>
  "! Every instance is uniquely identified by attributes
  "! carrier_id,
  "! connection_id, and
  "! flight_date.  
  CLASS lcl_flight DEFINITION ABSTRACT.

  4. ローカルクラス LCL_PASSENGER_FLIGHT の文書へのリンクと、ローカルクラス LCL_CARGO_FLIGHT の文書へのリンクを追加します。

    注記

    この ABAP Doc 文書は、ローカルクラス LCL_FLIGHT の内部ではなく、グローバルクラスレベルにあります。つまり、リンクの先頭にあるピリオド記号がグローバルクラスに対応します。同じグローバルクラスのローカルクラスをアドレスするには、クラス名の前にピリオド記号を付ける必要があります。

    1. コードを以下のように調整します。

      ABAP
      12345678
        "! Abstract superclass for classes 
  "! {@link .lcl_passenger_flight} and 
  "! {@link .lcl_cargo_flight} <br/>
  "! Every instance is uniquely identified by attributes
  "! carrier_id,
  "! connection_id, and
  "! flight_date.  
  CLASS lcl_flight DEFINITION ABSTRACT.

  5. ローカルクラス LCL_FLIGHT の属性 carrier_id、connection_id、および flight_date にリンクを追加します。

    注記

    リンク内の属性またはその他のデータオブジェクトを参照する場合は、オブジェクト名の直前に DATA: を挿入する必要があります。

    1. コードを以下のように調整します。

      ABAP
      12345678
        "! Abstract superclass for classes 
  "! {@link .lcl_passenger_flight} and 
  "! {@link .lcl_cargo_flight} <br/>
  "! Every instance is uniquely identified by attributes
  "! {@link .lcl_flight.DATA:carrier_id},
  "! {@link .lcl_flight.DATA:connection_id}, and
  "! {@link .lcl_flight.DATA:flight_date}.
  CLASS lcl_flight DEFINITION ABSTRACT.

  6. ローカルクラス LCL_FLIGHT の ABAP エレメント情報を照会して、出力を確認します。リンクを選択して、それらが動作することを確認します。

    1. CLASS … DEFINITION 命令で、lcl_flight にカーソルを置き、F2 を押してエレメント情報を表示します。

    2. ABAP Doc テキストがヘッダ Documentation の下に表示されます。

  7. 最後に、コードを有効化します。

    1. Ctrl + F3 を押してコードを有効化します。

Learning

SAP FacebookSAP YoutubeSAP LinkedIn