diff --git a/en/contribute/template/js-template.md b/en/contribute/template/js-template.md index 70002f0f5080c274867ccea5a6741a7d4d021aa5..037e3ffce7bf743bc78828cec405643bad507a7b 100644 --- a/en/contribute/template/js-template.md +++ b/en/contribute/template/js-template.md @@ -97,7 +97,7 @@ import call from '@ohos.telephony.call'; **System capability**: SystemCapability.*A.B* (This part is mandatory.) -| Name | Type | Readable| Writable| Description | +| Name | Type | Read Only| Mandatory| Description | | ---------------- | ----------------------------------------- | ---- | ---- | ------------------------------------------ | | pluggedType | [BatteryPluggedType]\(#batterypluggedtype) | Yes | No | Charger type of the current device. | | isBatteryPresent | boolean | Yes | No | Whether the battery is supported or present.| @@ -112,10 +112,10 @@ import call from '@ohos.telephony.call'; **System capability**: SystemCapability.*A.B* (This part is mandatory.) -| Name | Type | | Description | -| ---------------- | ----------------------------------------- | ------------------------------------------ | ------------------------------------------ | -| uid | number | 1 | User identifier (UID) of a process. | -| pid | number | 2 | Process ID (PID) of a process. | +| Name | Type | Value | Description | +| ---------------- | -----------------------------------| -------- | ------------------------------------------ | +| uid | number | 1 | User identifier (UID) of a process. | +| pid | number | 2 | Process ID (PID) of a process. | ## Methods @@ -154,15 +154,15 @@ Describe the method. For details, see the fourth and fifth points in "Writing In | Name | Type | Mandatory| Description | | ------------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | -| parameterOne | number \| string \| [CustomType](#customtype) | Yes | Describe the parameter. Provide the value range and recommended value. If there is a fixed format, provide a format example, especially for the URI.
Provide a link for each custom parameter type.| -| callback | Callback\> | No | Describe the parameter. For an optional parameter, describe the consequences if it is not specified.
Example: If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.
For details about how to write callback methods, see item 14 in "General Writing Instructions."| +| parameterOne | number \| string \| [CustomType](#classinterface) | Yes | Describe the parameter. Provide the value range and recommended value. If there is a fixed format, provide a format example, especially for the URI.
Provide a link for each custom parameter type.| +| callback | Callback\> | No | Describe the parameter. For an optional parameter, describe the consequences if it is not specified.
Example: If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.
For details about how to write callback methods, see item 14 in "General Writing Instructions."| **Return value** (This part is optional. Delete it if there is no return value.) | Type | Description | | ------------------------------------------ | ----------------------------------------------- | | string | Describe the return value, for example, what can be done after the return value is obtained.| -| Promise\> | Describe the return value. For details about how to write promise methods, see item 14 in "General Writing Instructions."| +| Promise\> | Describe the return value. For details about how to write promise methods, see item 14 in "General Writing Instructions."| **Error codes** (This part is optional. Delete it if no error code is thrown.) @@ -220,7 +220,7 @@ Describe the method. For details, see the fourth and fifth points in "Writing In | Name | Type | Mandatory| Description | | -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | Yes | Describe the event and when or how it will be triggered. If a method involves multiple events, describe them separately.
**Example 1 (single event):**
Type of the event. The **'play'** event is triggered when the **play()** API is called and audio playback starts.
Example 2 (multiple events):
Type of the event. The following events are supported:
- **'play'**: triggered when the **play()** API is called and audio playback starts.
- **'dataLoad'**: triggered when the audio data is loaded, that is, when the **src** attribute is configured.
- **'finish'**: triggered when the audio playback is finished. | -| callback | Callback\<[CustomType](#customtype)> | No | Describe the parameter. The instructions are the same as those provided under [Methods](#methods). | +| callback | Callback\<[CustomType](#classinterface)> | No | Describe the parameter. The instructions are the same as those provided under [Methods](#methods). | **Return value** (This part is optional. Delete it if there is no return value.) @@ -254,7 +254,7 @@ Describe the method. For details, see the fourth and fifth points in "Writing In > 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 class or interface contains only attributes, you do not need to create a level-3 heading. Instead, use a table to display the attributes. For details, see [CustomType](#customtype). +> 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. @@ -262,7 +262,7 @@ Describe the class or interface. If there are usage restrictions, describe them > *Writing Instructions* > -> Except that a level-3 heading is used for attributes in classes/interfaces, other instructions are the same as those provided under [Attributes](#attributes). +> Except that level-3 headings are used, other requirements are the same as those in [Attribute](#Attribute). ### Methods in Classes/Interfaces @@ -289,43 +289,29 @@ Provide a brief description of the enum type. Example: Enumerates the charger ty | ---- | ---- | -------------------------- | | NONE | 1 | Unknown type.| -## CustomType - -> *Writing Instructions* -> -> This section is optional. Delete it if there is no custom type. It corresponds to **Interface** in the .d.ts file. - -The following is an example of the custom type of a key-value pair. - -**System capability**: SystemCapability.*A.B* (This part is mandatory.) - -| Name | Type | Mandatory | Description | -| ------------ | ------------------- | ---- | ------------------------------------------------------------ | -| parameterUrl | string | Yes | Media output URI. Supported:
1. Relative path whose protocol type is **internal**. Example:
Temporary directory: internal://cache/test.mp4
2. Absolute path. Example:
file:///data/data/ohos.xxx.xxx/files/test.mp4| -| parameterOne | [CustomEnum](#enums)| No | Describe the attributes. The requirements are similar to those for the parameter description. | - -## Type +## 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. By default, use **Type** as the heading of the first column. If all the values are specific strings, change the heading of the first column to **Value**. +> 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 a type is of a custom type, create a link to the corresponding interface or enum. +> 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.) -| Type | Description | +| Value Range | Description | | -----------| ---------------------------- | -| number | The value is a number. | -| string | The value is a string. | +| number | The value can be any number. | +| string | The value can be any string. | ## Change History | Change Description | Date | | ----------------------------------------------------------------------- | ------------ | +| 1. Changed the template for **Attributes** from **Read**, **Write**, and **Mandatory** to **Read Only** and **Mandatory**.
2. Changed the template for **Types** by using **Value Range** and **Description**, and provided the related description.
3. Deleted the custom type, and incorporated the related description under **Classes/Interfaces**.| 2023/02/01 | | 1. Provided the general writing instructions in a table.
2. Added the description about how to reference an image in "Upload path".
3. Added the "Document structure" item to describe the sequence of nodes in the API reference document.
4. Added the description for multiple permissions in "Permission description".
5. Added the description of @FAModelOnly and @StageModelOnly in the API reference document.
6. Added the description of asynchronous methods (callback and promise).
7. Added the standards and specifications for the sample code programming language.
8. Added the standard format for links used in the API reference document.
9. Added examples for "Module description".
10. Added the description of on and off subscription methods.
11. Updated the description of @syscap.
12. Updated the description of @systemapi. Now only the sentence "This is a system API." is used.
13. Deleted the MR version description. | 2022/6/24 | | Added the error code description. | 2022/10/11 | | 1. Added the template for **constant** and **type**.
2. Modified the table of the custom type **interface** by deleting the **Readable** and **Writable** columns and adding the **Mandatory** column, for consistency with the content of the .d.ts file.
3. Added the deprecated description for APIs with both the initial version and deprecated version. |2022/11/22 |