API Reference Template

General Writing Instructions

NOTE

Delete all writing instructions after you finish the writing.

Mappings Between d.ts Tags and Document Fields

Except for @since, document fields mapping to the following tags must be provided under each API.

For an attribute or interface table, if a tag has the same value for all the items in the table, you can place the tag description above the table. Otherwise, place the tag under NOTE for each item.

The following describes the instructions for writing a specific API reference document.

Document Title

Writing Instructions

1. Document title: Use phrases that summarize the module functionalities. Examples: Ability and SIM Card Management
2. Heading levels: Use the document title as the level-1 heading, which is prefixed with # followed by a space. Use the attributes, functions, classes, interfaces, enums, and types under the namespace as level-2 headings, which are prefixed with ## followed by a space. Use the attributes and functions under classes as level-3 headings, which are prefixed with ### followed by a space.
3. Initial version description: Use the greater-than symbol (>) to indent the description about the initial version of the module. Use a line break after NOTE.
   Place the version description after the module description. A module has only one initial version.
   Use the following sentence: "The initial APIs of this module are supported since API version x. Newly added APIs will be marked with a superscript to indicate their earliest API version." Change x to the actual version number.

Describe the module from its functionalities, use cases, and recommendations in this section.

Example 1: description of the background task management module

This module provides background task management. If a service needs to be continued when the application or service module is running in the background (not visible to users), the application or service module can request a transient task or continuous task for delayed suspension based on the service type.

Example 2: description of the call module

The call module provides call management functions, including making calls, redirecting to the dial screen, obtaining the call status, and formatting phone numbers. To subscribe to the call state, use observer.on('callStateChange').

Example 3: description of the distributed data management module

The distributed data management module provides collaboration between databases of different devices for applications. The APIs provided by distributed data management can be used to save data to the distributed database and perform operations such as adding, deleting, modifying, querying, and synchronizing data in the distributed database.

Example 4: description of the linear container ArrayList module

ArrayList is a linear data structure that is implemented based on arrays. ArrayList can dynamically adjust the capacity based on project requirements. It increases the capacity by 50% each time. Similar to ArrayList, Vector is also implemented based on arrays and can dynamically adjust the capacity. It increases the capability by 100% each time. When compared with LinkedList, ArrayList is more efficient in random access but less efficient in the addition or removal operation, because its addition or removal operation affects the position of other elements in the container. You are advised to use ArrayList when elements in a container need to be frequently read.

NOTE

The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

Writing Instructions

1. Write the modules to import based on the actual conditions. Provide the import statement in the form of a code block.

2. If no module needs to be imported, change "Modules to Import" to "Usage" and provide a usage description.
   Example of Usage:
   Before using the AbilityContext, obtain the Context object through [getContext()](API-reference.md).

   import ability_featureAbility from '@ohos.ability.featureAbility';
   var context = ability_featureAbility.getContext();

import call from '@ohos.telephony.call';

Attributes

Writing Instructions

1. This section is optional. Delete it if there is no attribute.

2. If an attribute is of a custom type, create a link to the corresponding interface or enum.

3. For a readable attribute, if it has a limited number of values with special meanings, enumerate the values.

4. For a writable attribute, if only fixed fields are supported, describe them.

System capability: SystemCapability.A.B (This part is mandatory.)

Constants

Writing Instructions

1. This section is optional. Delete it if there is no constant. It corresponds to const in the .d.ts file.

2. If a constant is of a custom type, create a link to the corresponding interface or enum.

System capability: SystemCapability.A.B (This part is mandatory.)

Methods

Writing Instructions

1. This section is optional. Delete it if there is no method. If there are multiple methods, describe them in separate level-2 headings, prefixed with ## followed by a space.

2. Use the actual method name, in the format of ClassName.methodName, as the level-2 heading. For a subscription method, add the subscription event to the method name.

   Example of a common method: sim.getSimIccId Example of a subscription method: sim.on('exampleEvent')

3. Method calling mode: The description must be the same as that in the .d.ts file and include the parameter type, parameter name, and return value type. Example: getNetworkState(slotId: number, callback: AsyncCallback<NetworkState>): void Note: The angle bracket (<>) may be identified as a label and not displayed. To ensure normal display, you can either add a backslash (\) (in the format of "\<>") or use escape characters &lt; and &gt;.

4. Method description: Describe the features implemented by the method and include the prerequisites for using the method, the impact of the method, and the permissions and system capabilities required to use the method. (Example of prerequisites: This method can be called only after the xx method is called; you must ensure that the connection to the Internet is normal. Example of impact: xx does not take effect after this method is called.)

5. Asynchronous methods: If there are asynchronous methods, describe their return type in the method description. For details, see item 14 in "General Writing Instructions."

6. Line feed in a table: Use <br> for line feed.

Provide the method name in the following format: (static if it is a static method) methodName (parameterName1: parameterType1, parameterName2: parameterType2, ...): returnValueType

Describe the method. For details, see the fourth and fifth points in "Writing Instructions" above.

Model restriction: This API can be used only in the FA model. (Delete this part if it is not involved.)

System API: This is a system API. (Delete this part if it is not involved.)

Required permissions: ohos.permission.examplePermission (Delete this part if no permission is involved.)

System capability: SystemCapability.A.B (This part is mandatory.)

Parameters (This part is optional. Delete it if there is no parameter.)

Return value (This part is optional. Delete it if there is no return value.)

Error codes (This part is optional. Delete it if no error code is thrown.)

For details about the error codes, see [moduleName Error Codes](link to the error code document of the corresponding module).

Example

// This part is mandatory.

// Check all sample code provided in the example.
// Minor errors such as missing symbols and variable inconsistency are unacceptable.
// Declare all variables that are used.

// Write an actual case that can be easily used, rather than the parameter names themselves. Use comments to describe the content that are not user-defined.
// Example: var result = xxx.createExample(parameterOne); // parameterOne is automatically obtained by scanning.

// Provide clear and concise comments in the following typical scenarios:
// 1. The meaning of a variable name or the code logic is not self-explanatory.
// 2. A complex algorithm or special syntax is involved.

On and Off Subscription Methods

Writing Instructions

1. The basic requirements are the same as those provided in Methods. The following describes only the differences.

2. Use the actual method name, in the format of ClassName.methodName plus the subscription event, as the level-2 heading. Examples: sim.on(?exampleEvent?) and on('play' | 'pause' | 'stop' | 'reset')

3. Method calling mode: The description must be the same as that in the .d.ts file and include the parameter type, event name, parameter name, and return value type. Example: on(type: 'ringerModeChange', callback: Callback<AudioRingMode>): void Note: The angle bracket (<>) may be identified as a label and not displayed. To ensure normal display, you can either add a backslash (\) (in the format of "\<>") or use escape characters &lt; and &gt;.

Provide the method name in the following format: (static if it is a static method) methodName (parameterName1: parameterType1, parameterName2: parameterType2, ...): returnValueType

Describe the method. For details, see the fourth and fifth points in "Writing Instructions" under Methods.

Model restriction: This API can be used only in the FA model. (Delete this part if it is not involved.)

System API: This is a system API. (Delete this part if it is not involved.)

Required permissions: ohos.permission.examplePermission (Delete this part if no permission is involved.)

System capability: SystemCapability.A.B (This part is mandatory.)

Parameters (This part is optional. Delete it if there is no parameter.)

Return value (This part is optional. Delete it if there is no return value.)

Example

// This part is mandatory. The instructions are the same as those provided under [Methods](#methods).

// Check all sample code provided in the example.
// Minor errors such as missing symbols and variable inconsistency are unacceptable.
// Declare all variables that are used.

// Write an actual case that can be easily used, rather than the parameter names themselves. Use comments to describe the content that are not user-defined.
// Example: var result = xxx.createExample(parameterOne); // parameterOne is automatically obtained by scanning.

// Provide clear and concise comments in the following typical scenarios:
// 1. The meaning of a variable name or the code logic is not self-explanatory.
// 2. A complex algorithm or special syntax is involved.

Classes/Interfaces

Writing Instructions

1. This section is optional. Delete it if there is no class or interface. If there are multiple classes or interfaces, describe them in multiple level-2 headings, prefixed with ## followed by a space.

2. Use the actual class or interface name as the level-2 heading.

3. If the class or interface contains both attributes and methods, write the attributes above the methods. Write their actual names in separate level-3 headings. If the API contains only attributes, you do not need to create a level-3 heading. Instead, use a table to display the attributes.

Describe the class or interface. If there are usage restrictions, describe them as well, for example, whether there is a prerequisite and whether an instance needs to be created by using any method.

Attributes in Classes/Interfaces

Writing Instructions

Except that level-3 headings are used, other requirements are the same as those in Attributes.

Methods in Classes/Interfaces

Writing Instructions

1. Use the actual method name as the level-3 heading. Do not add a prefix. For a subscription method, add the corresponding subscription event to the method name. Example of a common method: getSimIccId Example of a subscription method: on('exampleEvent')
2. Other instructions are the same as those provided under Methods.

Enums

Writing Instructions

1. This section is optional. Delete it if there is no enum. If there are multiple enums, describe them in separate level-2 headings, prefixed with ## followed by a space.

2. Use the actual enum name as the level-2 heading, for example, BatteryHealthState.

Provide a brief description of the enum type. Example: Enumerates the charger types.

System capability: SystemCapability.A.B (This part is mandatory.)

Types

Writing Instructions

1. This section is optional. Delete it if there is no type. It corresponds to type in the .d.ts file.

2. If the value range is of a specific value, such as a fixed string or enumerated value, describe the data type and specified value. If the value range is of a specified type, describe whether any value of the type or a value range is used.

3. If the type is of a custom type, create a link to the corresponding interface or enum.

Provide a brief description of the union type. Example: Enumerates the value types.

System capability: SystemCapability.A.B (This part is mandatory.)

Change History