From da14fb7b19bc9f532b6cfd5d43e953361eb38e15 Mon Sep 17 00:00:00 2001 From: wusongqing Date: Wed, 3 Nov 2021 09:14:12 +0800 Subject: [PATCH] updated templates Signed-off-by: wusongqing --- .../template/concept-overview-template.md | 111 ++++++++++++++++ en/contribute/template/faq-template.md.md | 40 ++++++ en/contribute/template/guide-template.md | 124 ++++++++++++++++++ .../template/tutorial-template.md.md | 48 +++++++ .../template/concept-overview-template.md | 2 + zh-cn/contribute/template/guide-template.md | 6 +- 6 files changed, 328 insertions(+), 3 deletions(-) create mode 100644 en/contribute/template/concept-overview-template.md create mode 100644 en/contribute/template/faq-template.md.md create mode 100644 en/contribute/template/guide-template.md create mode 100644 en/contribute/template/tutorial-template.md.md diff --git a/en/contribute/template/concept-overview-template.md b/en/contribute/template/concept-overview-template.md new file mode 100644 index 0000000000..75a1216d50 --- /dev/null +++ b/en/contribute/template/concept-overview-template.md @@ -0,0 +1,111 @@ +# Overview Template + +##Basic Concepts + +***[Writing Requirements]*** + +*Mandatory. Describe basic concepts related to a development task to help developers better understand the task. The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.* + +| Requirement| Satisfied or Not| +| -------- | -------- | +| Common concepts in the industry are not described.| | +| Common terms in the industry, rather than internal terms, are used.| | + + +***[Example]*** + + +The XX system provides the audio module for your application to implement audio-related features, including audio playback, recording, and volume management. + + +It is considered good practice that you understand the following concepts before starting application development: + + +- Sampling + Sampling is a process where analog signals are converted into digital signals that can be represented by 0101. + +- Sampling rate + Sampling rate is the number of samples extracted from a continuous signal per second to form a discrete signal. It is measured in Hz. Generally, human hearing range is from 20 Hz to 20 kHz. Common audio sampling rates include 8 kHz, 11.025 kHz, 22.05 kHz, 16 kHz, 37.8 kHz, 44.1 kHz, 48 kHz, 96 kHz, and 192 kHz. + +- Channel + Channels refer to different spatial positions where independent audio signals are recorded or played. The number of channels is the number of audio sources used during audio recording, or the number of speakers used for audio playback. + +- Audio frame + Audio data is in stream form. For the convenience of audio algorithm processing and transmission, it is generally agreed that a data amount in a unit of 2.5 to 60 milliseconds is one audio frame. This unit is called sampling time, and its length is specific to codecs and the application requirements. + + +## Working Principles + +***[Writing Requirements]*** + +*Optional. You can delete this section if the working principles are simple and the basic concepts in the **Overview** section are enough for understanding.* + +*Describe the implementation principles, for example, the time for calling the APIs and triggering callbacks related to key steps, to help developers better understand the basic operation principles, carry out development tasks, and locate problems.* + +*The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.* + +| Requirement| Satisfied or Not| +| -------- | -------- | +| Only principles related to the development task are described.| | +| Supplementary graphics are used, such as sequence diagrams and flowcharts. The text description is consistent with the figure description.| | + +***[Example 1]*** + +- Semaphore initialization: The system allocates memory for the semaphores configured (the value of *N* can be configured by users and is limited by the memory), initializes all semaphores to be unused semaphores, and adds them to a linked list for the system to use. + +- Semaphore creation: The system obtains a semaphore from the linked list of unused semaphores and assigns an initial value to the semaphore. + +- Semaphore request: If the counter value is greater than 0, the system allocates a semaphore, decreases the value by 1, and returns a success message. Otherwise, the system blocks the task and adds the task to the end of a task queue waiting for semaphores. The wait timeout period can be set. + +- When a semaphore is released, if there is no task waiting for it, the counter is increased by 1. Otherwise, the first task in the wait queue is woken up. + +- Semaphore deletion: The system sets a semaphore in use to the unused state and inserts it to the linked list of unused semaphores. + +- Semaphore allows only a specified number of tasks to access a shared resource at a time. When the number of tasks accessing the resource reaches the limit, other tasks will be blocked until the semaphore is released. + + + ***[Example 2]*** + + **Working Principles of Mutexes** + + In a multi-task environment, multiple tasks may access the same shared resource. However, certain shared resources are not shared, and can only be accessed exclusively by tasks. A mutex can be used to address this issue. + + When non-shared resources are accessed by a task, the mutex is locked. Other tasks will be blocked until the mutex is released by the task. The mutex allows only one task to access the shared resources at a time, ensuring integrity of operations on the shared resources. + + + +## Limitations and Constraints + +***[Writing Requirements]*** + +*Mandatory. Describe the constraints of the development task and the negative impact of the constraints, including but not limited to the following:* + +- ***[Function Limitations]*** + - *Application scope of the function (specify scenarios that are not supported)* + - *Specification limitations* + +***Operation constraints**:* + + *Operations on known issues* + *Potentially risky operations (such as performance deterioration)* + *Operations that may cause performance deterioration* + +*The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.* + +| Requirement| Satisfied or Not| +| -------- | -------- | +| The function limitations or operation restrictions are clearly specified.| | +| Only constraints that affect task development or user experience are described.| | +| Operations that are prone to errors are described in the procedure but not described in this section.| | + +***[Example]*** + +**Limitations and Constraints on Mutexes:** + +- Two tasks cannot lock the same mutex. If a task attempts to lock a mutex held by another task, the task will be blocked until the mutex is unlocked. + +- Mutexes cannot be used in the interrupt service program. + +- When using the LiteOS-A kernel, the xx system must ensure real-time task scheduling and avoid long-time task blocking. Therefore, a mutex must be released as soon as possible. + +- When a mutex is held by a task, the task priority cannot be changed by using APIs such as **LOS_TaskPriSet**. diff --git a/en/contribute/template/faq-template.md.md b/en/contribute/template/faq-template.md.md new file mode 100644 index 0000000000..e3d11b739f --- /dev/null +++ b/en/contribute/template/faq-template.md.md @@ -0,0 +1,40 @@ +# FAQ Template + +FAQs describe issues encountered during development and provide solutions to the issues. + +## Title Requirements + +Briefly describe the key information about an issue in the title. + +## Template for Writing Minor Issues + +Briefly describe the operations, issues, and solutions. + +## Template for Writing Complex Issues + +**Symptom** + +- System software and version in use +- Problem description and trigger conditions + +- Error messages + +- Screenshots, if available + + +**Possible Causes** + +Analyze the causes of the issue. If there are multiple possible causes, list them one by one. + +1. XXX +2. XXX + +**Solutions** + +- If there are multiple solutions, arrange them in order from least complex to most complex, and provide their respective scenarios. +- If possible, provide screenshots to help understand the steps. +- If the code has print output, provide the output content separately to help understand the solution procedure. + +1. XXX +2. XXX + diff --git a/en/contribute/template/guide-template.md b/en/contribute/template/guide-template.md new file mode 100644 index 0000000000..3a530df67f --- /dev/null +++ b/en/contribute/template/guide-template.md @@ -0,0 +1,124 @@ +# Development Guidelines + +***[Writing Requirements]*** + + +*Mandatory. Describe how a developer completes tasks in a specific scenario. Include one scenario in each section. The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.* + + +| Requirement| Satisfied or Not| +| -------- | -------- | +| Each section covers only one scenario. If there are multiple scenarios, provide development guidelines for each scenario in separate sections. For example, you can use the following sections in **Audio**: **Development Guidelines on Audio Playback**, **Development Guidelines on Volume Management**, and **Development Guidelines on Sound Playback**.| | +| Use verbs + nouns to describe task operations in titles.| | + + +## When to Use + +***[Writing Requirements]*** + +*Mandatory. Describe in which scenario, what problem is solved, and what the final effect is. Use the SCQA method.* + +- *S: situation. Introduce a familiar scenario.* + +- *C: complication. Describe the conflict between the situation and requirement.* + +- *Q: question. Ask a question. What can I do in such a case?* + +- *A: answer. Describe the solution.* + +*The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.* + +| Requirement| Satisfied or Not| +| -------- | -------- | +| Clearly describe the background, what operations are done when and where, what problems are solved, and what benefits are delivered.| | + +***[Example]*** + +You can use APIs described in this section to convert audio data into audible analog signals, play the audio signals using output devices, and manage playback tasks. + + +## Available APIs + +***[Writing Requirements]*** + +*Mandatory. Describe APIs involved in the development guideline to help developers have a general understanding of the APIs, thereby improving development efficiency. The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.* + +| Requirement| Satisfied or Not| +| -------- | -------- | +| Include only APIs relevant to the development task.| | +| If there are more than 10 APIs, you can provide only main APIs.| | + +***[Example]*** + +The **AudioRenderer** class provides open audio playback capabilities. For details about the APIs, see the API reference. + +**Table 1** Audio playback APIs + +| API| Description| +| -------- | -------- | +| AudioRenderer(AudioRendererInfo audioRendererInfo, PlayMode pm) throws IllegalArgumentException | A constructor used to create an **AudioRenderer** instance based on the specified playback parameters, the specified playback mode, and the default playback device.| +| AudioRenderer(AudioRendererInfo audioRendererInfo, PlayMode pm, AudioDeviceDescriptor outputDevice) throws IllegalArgumentException | A constructor used to create an **AudioRenderer** instance based on the specified playback parameters, playback mode, and playback device.| +| boolean play() | Plays audio streams.| +| boolean write(byte[] data, int offset, int size) | Writes audio data in the specified byte array into an audio receiver for playback.| + + +## How to Develop + +***[Writing Requirements]*** + + *Mandatory. Describe the overall process to help developers quickly complete the task. The table below describes the writing requirements. After finishing the writing, check your content against these requirements one by one.* +| Requirement| Satisfied or Not| +| -------- | -------- | +| **Writing a Development Procedure**| | +| Complete: All mandatory steps are provided.| | +| Clear: The logic of the writing is clear and reasonable. The overview, preparations, and operations in the document are described by following certain logic, and the chapters are not broken or contradictory.| | +| Sentence pattern for tasks: Use verbs + nouns to describe actions in titles or sentences.| | +| Prevention in advance: Describe the restrictions, error-prone operations, and potential risks in advance. Use general icons and styles.| | +| Clear steps-1: Describe the purpose of each step, no matter whether it is simple or not.| | +| Clear steps-2: Specify the environment, tools, operations, and how-to.| | +| If an operation is optional, specify the optional conditions.| | +| After the development procedure is complete, specify the expected results.| | +| **Writing a Code Segment**| | +| If a code segment involves commands to be copied by developers, display the commands in editable mode, instead of using screenshots. Use code snippets to wrap the commands.| | +| Highlight key code segments in blue (RGB: 0.0.255), and comment out key steps.| | +| The code display meets the code indentation requirements.| | +| If an API call is involved in a step, provide the API and its usage description or sample code. The code comes from specific instances.| | + +***[Example]*** + +1. Use **AudioStreamInfo.Builder** to create an **AudioStreamInfo** instance for audio stream parameters. The following example uses the default values of the input parameters for **AudioStreamInfo.Builder**. You need to set the parameters based on the audio stream specification. + ``` + AudioStreamInfo audioStreamInfo = new AudioStreamInfo.Builder().sampleRate( AudioStreamInfo.SAMPLE_RATE_UNSPECIFIED) .audioStreamFlag(AudioStreamInfo.AudioStreamFlag.AUDIO_STREAM_FLAG_NONE) .encodingFormat(AudioStreamInfo.EncodingFormat.ENCODING_INVALID) .channelMask(AudioStreamInfo.ChannelMask.CHANNEL_INVALID) .streamUsage(AudioStreamInfo.StreamUsage.STREAM_USAGE_UNKNOWN) .build(); + ``` + + Example code for playing a PCM stream: + ``` + AudioStreamInfo audioStreamInfo = new AudioStreamInfo.Builder().sampleRate(44100)// 44.1 kHz .audioStreamFlag(AudioStreamInfo.AudioStreamFlag.AUDIO_STREAM_FLAG_MAY_DUCK)// Set audio ducking. .encodingFormat(AudioStreamInfo.EncodingFormat.ENCODING_PCM_16BIT)//16-bit PCM .channelMask(AudioStreamInfo.ChannelMask.CHANNEL_OUT_STEREO)// Set the dual output channel. .streamUsage(AudioStreamInfo.StreamUsage.STREAM_USAGE_MEDIA)// Set the stream to be used for media. .build(); + ``` + +2. Build the playback parameter structure via **AudioRendererInfo** for the audio stream created in Step 1, and use **AudioRendererInfo.Builder** to create an #lt;ph class="- topic/ph " id="ph96666347177" status="new"/#gt;instance. The following example uses the default parameter values of the **AudioRendererInfo.Builder** instance. You need to set the playback parameters based on the audio playback specification. + ``` + AudioRendererInfo audioRendererInfo = new AudioRendererInfo.Builder().audioStreamInfo(audioStreamInfo) .audioStreamOutputFlag(AudioRendererInfo.AudioStreamOutputFlag.AUDIO_STREAM_OUTPUT_FLAG_NONE) .bufferSizeInBytes(0) .distributedDeviceId("") .isOffload(false) .sessionID(AudioRendererInfo.SESSION_ID_UNSPECIFIED) .build(); + ``` + + Example code for playing a PCM stream: + ``` + AudioRendererInfo audioRendererInfo = new AudioRendererInfo.Builder().audioStreamInfo(audioStreamInfo) .audioStreamOutputFlag(AudioRendererInfo.AudioStreamOutputFlag.AUDIO_STREAM_OUTPUT_FLAG_DIRECT_PCM)// Set direct PCM output .bufferSizeInBytes(100) .distributedDeviceId("E54***5E8")// Use distributed device E54***5E8 for playback. .isOffload(false)// Value false indicates that the audio stream is transmitted to the buffer on a segment-by-segment basis for several times and then played. Value true indicates that the audio stream is transmitted to the HAL layer at a time. .build(); + ``` + +3. Specify the playback mode based on the audio stream to be played. The playback modes differ only in the data writing process. + .... + +4. After the playback task is complete, call the **release()** method on the **AudioRenderer** instance to release resources. + + +## (Optional) Commissioning and Verification + +***[Writing Requirements]*** + +*Optional. After the development is complete, perform commissioning and verification to ensure that the operation is successful. The operation procedure requirements are the same as those in **Development Guidelines**. Other specific writing requirements are as follows. After finishing the writing, check your content against these requirements one by one.* + +| Requirement| Satisfied or Not| +| -------- | -------- | +| Describe the final service commissioning process. The operation result of each step should be verified after the corresponding development task is complete.| | +| Specify the criteria for development success.| | diff --git a/en/contribute/template/tutorial-template.md.md b/en/contribute/template/tutorial-template.md.md new file mode 100644 index 0000000000..d8f7a7382d --- /dev/null +++ b/en/contribute/template/tutorial-template.md.md @@ -0,0 +1,48 @@ +# Tutorial Template + +A tutorial describes how to develop a complex task, feature, and application. Usually, the development process is divided into several sections, each with a series of steps. In addition, code examples are provided to help developers understand the specific feature implementation. + +You should explain basic concepts mentioned in the tutorial, and suggest developers refer to specific corresponding topics in developer-oriented documents for in-depth concepts. + +When you write the tutorial page, create a **MarkDown** file in the **others** directory. + +## Overview + +Content: Describe the tasks that developers will do and the features and effects that developers will achieve after learning this tutorial. If multiple goals can be achieved, it is recommended that you use a bulleted list. + +If possible, provide pictures or short videos to demonstrate the effect. + +## Preparations + +- Provide the information about the required software, hardware, tools, and their version information. +- Describe required permissions. + +## _XXX_ \(Key Task 1\) + +Break down the tutorial into several sequential critical tasks or parallel scenario-specific tasks. + +1. XXXX + + ``` + // Sample code + ``` + +2. XXXX + +Comply with the following writing instructions on how to describe operations: + +1. Specify the operation scenario and purpose for each step, and clarify the actor of each action. +2. Provide API descriptions and related sample codes if needed. +3. Provide screenshots of GUI-based steps for better understanding. +4. Ensure that code logic and syntax are correct. +5. Provides comments for key steps in the code. +6. Provide the output content if any. + +## XXX \(Key Task 2\) + +1. XXXX + +## Next + +Describe the subsequent development tasks that may be associated with this tutorial. If there are no associated tasks, skip this topic. + diff --git a/zh-cn/contribute/template/concept-overview-template.md b/zh-cn/contribute/template/concept-overview-template.md index 25af35d564..65046e1557 100644 --- a/zh-cn/contribute/template/concept-overview-template.md +++ b/zh-cn/contribute/template/concept-overview-template.md @@ -1,5 +1,7 @@ # 概述 +## 基本概念 + *【 **写作要求】*** *必选，描述本开发任务相关的基本概念，帮助开发者更好的理解开发任务。* *写作要求见下，完成写作后，请逐项自检。* diff --git a/zh-cn/contribute/template/guide-template.md b/zh-cn/contribute/template/guide-template.md index dfa06b315e..8305f34c38 100644 --- a/zh-cn/contribute/template/guide-template.md +++ b/zh-cn/contribute/template/guide-template.md @@ -28,9 +28,9 @@ *写作要求见下，完成写作后，请逐项自检。* -| 要求项 | 内容要求 | 是否满足 | -| -------- | -------- | -------- | -| I.1.1 | 背景原因、什么时候在哪、做了什么操作、最终解决什么问题或操作效果都明确。 | | +| 内容要求 | 是否满足 | +| -------- | -------- | +| 背景原因、什么时候在哪、做了什么操作、最终解决什么问题或操作效果都明确。 | | **【写作样例】** -- GitLab