记录 ABAP 代码

学习目标

  • 记录 ABAP 代码。

ABAP 代码文档

如果将光标置于类、方法或类型的名称上，然后按 F2，您将看到一个包含相应元素信息的对话框窗口。

您可以使用 ABAP Doc 向此对话框添加文档。通过向代码添加特殊注释行来创建此文档。使用 ABAP Doc，您可以记录以下声明语句：

  • CLASS

  • INTERFACE

  • METHODS

  • TYPES

  • DATA

  • CONSTANTS

您还可以记录方法和功能模块的各个参数和例外。

ABAP 文档注释位于其记录的元素之前。它们以字符 "! 开头。如果尝试在不允许的类中的位置创建 ABAP 文档，系统将显示语法警告，并忽略文档。

无法翻译 ABAP Doc 注释。因此，您应该仔细考虑要使用哪种语言创建文档。

您的 ABAP 文档注释将成为元素文档的一部分。

ABAP 文档使用 HTML 标记子集来格式化文档。该示例使用 <strong> 标记表示 emphasis，使用 <br> 标记表示换行。（请注意，如果没有换行符标签，ABAP 文档的两行将彼此相邻显示）。

除强强调文本和换行符外，您还可以使用以下标记：

ABAP 文档中的附加格式标记

用途

格式化标签

抬头，级别 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 + 空格）插入格式设置标记。

使用 ABAP 文档，您可以同时记录方法及其各个参数。要记录该方法，请使用常规 "! 注释。要记录参数，请使用注释 "! @parameter <name> | 并在竖线字符 (|) 后添加注释。

您可以使用快速修复为方法及其签名添加 ABAP 文档。声明方法后，按 Ctrl + 1 打开可能的快速修复，然后选择添加 ABAP 文档。然后，编辑器会生成相应的文档。

如果方法的签名发生更改，则可以使用快速修复删除已删除参数的 ABAP 文档注释，并为新参数添加 ABAP 文档注释。

可以确保在对象属性和对象列表的描述中复制对象的 ABAP 文档描述。为此，请使用带有附加项 <p> 的段落标记 class="shorttext synchronized"。

在对象属性中对描述所做的更改将复制到 ABAP Doc 注释。

您可以将导航链接添加到其他对象的文档。

除了链接到整个对象外，还可以链接到其各个元素。在我们的示例中，存在方法 GET_AIRPORTS 的链接。- 链接 "! {@link zif_1_abap_doc_constants.DATA:auth_create} 定义接口 ZIF_1_ABAP_DOC_CONSTANTS 中常量 auth_create 文档的链接。

将以下标识用于单个元素：

DATA

用于相应上下文中的常量、变量和过程参数

DOMA

用于 ABAP 字典中的域

INTF

用于在类中实施的接口（用于访问接口组件）

METH

对于方法

如何使用 ABAP 文档记录代码

观看此视频，了解如何使用 ABAP 文档记录代码。

视频：本节含 SAP 官方视频（视频 ID 1_nx6tloze），需在 learning.sap.com 在线观看。

将文档添加到 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，其中 ## 代表组编号）。

  2. 在项目浏览器中，右键单击类 /LRN/CL_S4D401_EXS_CLASS 以打开上下文菜单。

  3. 从上下文菜单中，选择复制....

  4. 在包字段中输入包的名称。在名称字段中，输入 ZCL_##_SOLUTION，其中 ## 代表组编号。

  5. 选择下一步。

  6. 确认传输请求并选择完成。

  7. 激活复制。

  8. 按 Ctrl + F3 激活类。

任务 2: 添加文档

将 ABAP 文档文档添加到本地类 LCL_CARRIER 和工厂方法 GET_INSTANCE。

建议的文档文本

类型

代码元素

文档

局部类

LCL_CARRIER

航班承运人 - 工厂逻辑确保每个承运人标识只能有一个实例。

方法

GET_INSTANCE

工厂方法 - 返回此类的实例。

参数

i_carrier_id

承运商的三字符标识。

参数

r_result

参考实例 - 如果实例化失败，则为初始值。

异常

ZCX_##_FAILED

实例化失败 - 评估异常文本以获取详细信息。

步骤

  1. 使用快速修复将 ABAP 文档文档添加到本地类 LCL_CARRIER。

  2. 在全局类中，导航到本地类 LCL_CARRIER 的定义。

  3. 在 CLASS…DEFINITION 语句中，将光标放在 lcl_carrier 上并按 Ctrl + 1 调用可用的快速修复。

  4. 从可用快速修复列表中，选择 添加 ABAP 文档 。

结果

快速修复按如下方式调整代码：

"!
CLASS lcl_carrier DEFINITION CREATE PRIVATE.

  1. 使用表中的文本维护文档。

提示

按 Enter 键时，编辑器将插入以"!

开头的新行。

  1. 如下调整代码：

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

  1. 显示本地类 LCL_CARRIER 的 ABAP 元素信息以查看输出。

  2. 在 CLASS…DEFINITION 语句中，将光标放在 lcl_carrier 上并按 F2 显示元素信息。

  3. ABAP 文档文本显示在文档标题下。

  4. 使用快速修复将 ABAP 文档文档添加到本地类 LCL_CARRIER 的静态方法 GET_INSTANCE。

  5. 在 LCL_CARRIER 类中，导航到方法 GET_INSTANCE 的定义。

  6. 在 CLASS-METHODS 语句中，将光标置于 get_instance 上，然后按 Ctrl + 1 调用可用的快速修复。

  7. 从可用快速修复列表中，选择 添加 ABAP 文档 。

结果

快速修复按如下方式调整代码：

"!
"! @parameter i_carrier_id |
"! @parameter r_result |
"! @raising zcx_##_failed |
CLASS-METHODS get_instance

  1. 使用表中的文本维护方法的文档。

  2. 如下调整代码：

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

  1. 使用表中的文本维护方法参数和异常的文档。

  2. 如下调整代码：

"! 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

  1. 显示本地类 LCL_CARRIER 的方法 GET_INSTANCE 的 ABAP 元素信息以查看输出。

  2. 在 CLASS-METHODS 语句中，将光标置于 get_instance 上，然后按 F2 显示元素信息。

  3. ABAP 文档文本显示在标题文档下。

任务 3: 添加格式化文档

为本地类 LCL_CARRIER 的方法 FIND_PASSENGER_FLIGHT 添加格式化 ABAP 文档文档。或者，为方法 FIND_CARGO_FLIGHT 添加类似的 ABAP 文档。

建议的文档文本

类型

代码元素

文档

方法

FIND_PASSENGER_FLIGHT

搜索两个机场之间的乘客航班位于给定日期或之后，并且已剩余 个最小可用座位

参数

i_airport_from_id

出发机场

参数

i_airport_to_id

到达机场

参数

i_from_date

第一个可能的航班日期

参数

i_casits

最小可用座位数

参数

e_flight

已找到航班（对象参考）

参数

e_days_later

请求日期后的天数

步骤

  1. 使用快速修复将 ABAP 文档文档添加到本地类 LCL_CARRIER 的方法 FIND_PASSENGER_FLIGHT。

  2. 在 LCL_CARRIER 类中，导航到方法 FIND_PASSENGER_FLIGHT 的定义。

  3. 在 METHODS 语句中，将光标置于 find_passenger_flight 上并按 Ctrl + 1 调用可用的快速修复。

  4. 从可用快速修复列表中，选择 添加 ABAP 文档 。

结果

快速修复按如下方式调整代码：

"!
"! @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

  1. 使用表中的文本维护方法的文档。确保将**乘客航班**格式化为强强调文本，并使用航班属性的未排序清单。

提示

你不必记住格式指令由心。按 Ctrl + 空格键通过代码完整化插入格式指令。

  1. 如下调整代码：

"! 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

  1. 使用表中的文本维护方法参数的文档。确保将出发和到达格式设置为强调文本。

  2. 如下调整代码：

"! 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

  1. 显示本地类 LCL_CARRIER 的方法 FIND_PASSENGER_FLIGHT 的 ABAP 元素信息以查看输出。

  2. 在 METHODS 语句中，将光标置于 find_passenger_flight ，然后按 F2 显示元素信息。

  3. ABAP 文档文本显示在标题文档下。

  4. 可选：为方法 FIND_CARGO_FLIGHT 添加类似的格式化 ABAP 文档文档。

提示

复制并粘贴方法 FIND_PASSENGER_FLIGHT 的 ABAP 文档文档并将其调整为方法 FIND_CARGO_FLIGHT。

  1. 如下调整代码：

"! 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 文档：

建议的文档文本

类型

代码元素

文档

局部类

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 文档文档添加到本地类 LCL_FLIGHT。

  2. 在全局类中，导航到本地类 LCL_FLIGHT 的定义。

  3. 在 CLASS…DEFINITION 语句中，将光标放在 lcl_flight 上并按 Ctrl + 1 调用可用的快速修复。

  4. 从可用快速修复列表中，选择 添加 ABAP 文档 。

结果

快速修复按如下方式调整代码：

"!
CLASS lcl_flight DEFINITION ABSTRACT.

  1. 使用表中的文本维护文档。

  2. 如下调整代码：

"! 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.

  1. 在 lcl_cargo_flight 后添加换行。

  2. 如下调整代码：

"! 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.

  1. 添加指向本地类 LCL_PASSENGER_FLIGHT 的文档链接和指向本地类 LCL_CARGO_FLIGHT 文档的链接。

注意

请记住，此 ABAP 文档文档位于全局类级别，不在本地类 LCL_FLIGHT 内。这意味着链接开头的句点符号用于寻址全局类。要处理同一全局类中的局部类，必须在类名前放置句点符号。

  1. 如下调整代码：

"! 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.

  1. 现在，添加指向本地类 LCL_FLIGHT 的属性 carrier_id、connection_id 和 flight_date 的链接。

注意

如果要在链接中引用属性或其他数据对象，则必须在对象名称前面插入 DATA: 。

  1. 如下调整代码：

"! 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.

  1. 显示本地类 LCL_FLIGHT 的 ABAP 元素信息以查看输出。选择链接以验证它们是否有效。

  2. 在 CLASS…DEFINITION 语句中，将光标放在 lcl_flight 上并按 F2 显示元素信息。

  3. ABAP 文档文本显示在文档标题下。

  4. 最后，激活您的代码。

  5. 按 Ctrl + F3 激活代码。