目录

Why does the @since X in the comment of an ArkTS API seem to be later than the actual introduction time of the API?

Symptom

When you view the comment of an ArkTS API in DevEco Studio or hover the mouse pointer over the ArkTS API call, you may find that the @since X (for example, @since 20) of some APIs is later than expected and they actually existed in earlier versions (such as API 19).

Possible Causes

Currently, HarmonyOS uses the "multi-segment comment" policy to record the change history of ArkTS APIs. Each time a major feature is added to an API or its behavior changes (for example, support for widgets or atomic services, or change of error codes), a new comment is added to record the change and the version in which the change takes effect (that is, @since X).

Solution

To confirm the initial version of an API, expand the complete ArkTS API comment and check the earliest @since X record.

Example

Take the inputMethodEngine.InputClient.getAttachOptions API in @ohos.inputMethodEngine.d.ts as an example:

declare namespace inputMethodEngine {
    interface InputClient {
        /**
         * Get input attachOptions.
         *
         * @returns { AttachOptions } return attach options.
         * @throws { BusinessError } 801 - Capability not supported.
         * @syscap SystemCapability.MiscServices.InputMethodFramework
         * @since 19
         */
        /**
         * Get input attachOptions.
         *
         * @returns { AttachOptions } return attach options.
         * @syscap SystemCapability.MiscServices.InputMethodFramework
         * @since 20
         */
        getAttachOptions(): AttachOptions;
    }
}

In this example, two comment segments are used to describe the changes in the API in API versions 19 and 20. The getAttachOptions() API was first introduced in API version 19. On devices that do not support this API, error code 801 will be thrown. Since API version 20, all devices support this API, and error code 801 will no longer be thrown.

Earliest Compatible Version of the Project

compatibleSdkVersion in build-profile.json5

Viewing the SDK Declaration File

Hovering the Mouse Pointer over the API Call

5.0.0 (12)

Only the latest @since 20 comment is displayed, and the rest information is collapsed.

The @since 19 and @since 20 comments are displayed in two segments.

5.1.1 (19)

Only the latest @since 20 comment is displayed, and the rest information is collapsed.

The @since 19 and @since 20 comments are displayed in two segments.

6.0.0 (20)

Only the latest @since 20 comment is displayed, and the rest information is collapsed.

Only the @since 20 comment is displayed.

You may mistakenly think that the API is newly added in API version 20. In fact, this API has been introduced since API version 19.