Merge branch 'docs/update_cn_for_api-conventions_backport_v5.1' into …

…'release/v5.1'

Docs: Translate api-conventions.rst (backport v5.1)

See merge request espressif/esp-idf!24121

docs/en/api-reference/api-conventions.rst

@@ -1,34 +1,35 @@
 API Conventions
 ===============
+:link_to_translation:`zh_CN:[中文]`
 
 .. highlight:: c
 
 This document describes conventions and assumptions common to ESP-IDF Application Programming Interfaces (APIs).
 
 ESP-IDF provides several kinds of programming interfaces:
 
-* C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-IDF components. Various pages in the API Reference section of the programming guide contain descriptions of these functions, structures and types.
-* Build system functions, predefined variables and options. These are documented in the :ref:`build system guide<cmake_buildsystem_api>`.
-* :doc:`Kconfig <kconfig>` options can can be used in code and in the build system (CMakeLists.txt) files.
-* :doc:`Host tools <../api-guides/tools/index>` and their command line parameters are also part of ESP-IDF interface.
+* C functions, structures, enums, type definitions, and preprocessor macros declared in public header files of ESP-IDF components. Various pages in the API Reference section of the programming guide contain descriptions of these functions, structures, and types.
+* Build system functions, predefined variables, and options. These are documented in the :ref:`ESP-IDF CMake Build System API <cmake_buildsystem_api>`.
+* :doc:`Kconfig <kconfig>` options can be used in code and in the build system (``CMakeLists.txt``) files.
+* :doc:`Host tools <../api-guides/tools/index>` and their command line parameters are also part of the ESP-IDF interfaces.
 
-ESP-IDF consists of components written specifically for ESP-IDF as well as third-party libraries. In some cases, an ESP-IDF-specific wrapper is added to the third-party library, providing an interface that is either simpler or better integrated with the rest of ESP-IDF facilities. In other cases, the original API of the third-party library is presented to the application developers.
+ESP-IDF is made up of multiple components where these components either contain code specifically written for ESP chips, or contain a third-party library (i.e., a third-party component). In some cases, third-party components will contain an "ESP-IDF specific" wrapper in order to provide an interface that is either simpler or better integrated with the rest of ESP-IDF's features. In other cases, third-party components will present the original API of the underlying library directly.
 
-Following sections explain some of the aspects of ESP-IDF APIs and their usage.
+The following sections explain some of the aspects of ESP-IDF APIs and their usage.
 
-Error handling
+Error Handling
 --------------
 
-Most ESP-IDF APIs return error codes defined with ``esp_err_t`` type. See :doc:`Error Handling <../api-guides/error-handling>` section for more information about error handling approaches. :doc:`Error Code Reference <error-codes>` contains the list of error codes returned by ESP-IDF components.
+Most ESP-IDF APIs return error codes defined with the :cpp:type:`esp_err_t` type. See :doc:`Error Handling <../api-guides/error-handling>` section for more information about error handling approaches. :doc:`Error Codes Reference <error-codes>` contains the list of error codes returned by ESP-IDF components.
 
 .. _api_reference_config_structures:
 
-Configuration structures
+Configuration Structures
 ------------------------
 
-.. important:: Correct initialization of configuration structures is an important part in making the application compatible with future versions of ESP-IDF.
+.. important:: Correct initialization of configuration structures is an important part of making the application compatible with future versions of ESP-IDF.
 
-Most initialization or configuration functions in ESP-IDF take as an argument a pointer to a configuration structure. For example::
+Most initialization, configuration, and installation functions in ESP-IDF (typically named ``..._init()``, ``..._config()``, and ``..._install()``) take a configuration structure pointer as an argument. For example::
 
     const esp_timer_create_args_t my_timer_args = {
         .callback = &my_timer_callback,
@@ -38,7 +39,7 @@ Most initialization or configuration functions in ESP-IDF take as an argument a
     esp_timer_handle_t my_timer;
     esp_err_t err = esp_timer_create(&my_timer_args, &my_timer);
 
-Initialization functions never store the pointer to the configuration structure, so it is safe to allocate the structure on the stack.
+These functions never store the pointer to the configuration structure, so it is safe to allocate the structure on the stack.
 
 The application must initialize all fields of the structure. The following is incorrect::
 
@@ -47,14 +48,14 @@ The application must initialize all fields of the structure. The following is in
     /* Incorrect! Fields .arg and .name are not initialized */
     esp_timer_create(&my_timer_args, &my_timer);
 
-Most ESP-IDF examples use C99 `designated initializers`_ for structure initialization, since they provide a concise way of setting a subset of fields, and zero-initializing the remaining fields::
+Most ESP-IDF examples use C99 `designated initializers`_ for structure initialization since they provide a concise way of setting a subset of fields, and zero-initializing the remaining fields::
 
     const esp_timer_create_args_t my_timer_args = {
         .callback = &my_timer_callback,
         /* Correct, fields .arg and .name are zero-initialized */
     };
 
-The C++ language supports designated initializers syntax, too, but the initializers must be in the order of declaration. When using ESP-IDF APIs in C++ code, you may consider using the following pattern::
+The C++ language supports designated initializer syntax, too, but the initializers must be in the order of declaration. When using ESP-IDF APIs in C++ code, you may consider using the following pattern::
 
     /* Correct, fields .dispatch_method, .name and .skip_unhandled_events are zero-initialized */
     const esp_timer_create_args_t my_timer_args = {
@@ -68,21 +69,19 @@ The C++ language supports designated initializers syntax, too, but the initializ
     //    .callback = &my_timer_callback,
     //};
 
-For more information on designated initializers, see :ref:`Designated initializers <cplusplus_designated_initializers>`. Note that C++ language versions older than C++20 (not the default in the current version of ESP-IDF) do not support designated initializers. If you have to compile code with an older C++ standard than C++20, you may use GCC extensions to produce the following pattern::
+For more information on designated initializers, see :ref:`cplusplus_designated_initializers`. Note that C++ language versions older than C++20, which are not the default in the current version of ESP-IDF, do not support designated initializers. If you have to compile code with an older C++ standard than C++20, you may use GCC extensions to produce the following pattern::
 
     esp_timer_create_args_t my_timer_args = {};
     /* All the fields are zero-initialized */
     my_timer_args.callback = &my_timer_callback;
 
-Default initializers
+Default Initializers
 ^^^^^^^^^^^^^^^^^^^^
 
 For some configuration structures, ESP-IDF provides macros for setting default values of fields::
 
     httpd_config_t config = HTTPD_DEFAULT_CONFIG();
-    /* HTTPD_DEFAULT_CONFIG expands to a designated initializer.
-       Now all fields are set to the default values.
-       Any field can still be modified: */
+    /* HTTPD_DEFAULT_CONFIG expands to a designated initializer. Now all fields are set to the default values, and any field can still be modified: */
     config.server_port = 8081;
     httpd_handle_t server;
     esp_err_t err = httpd_start(&server, &config);
@@ -94,58 +93,58 @@ It is recommended to use default initializer macros whenever they are provided f
 Private APIs
 ------------
 
-Certain header files in ESP-IDF contain APIs intended to be used only in ESP-IDF source code, and not by the applications. Such header files often contain ``private`` or ``esp_private`` in their name or path. Certain components, such as :doc:`hal <../api-guides/hardware-abstraction>` only contain private APIs.
+Certain header files in ESP-IDF contain APIs intended to be used only in ESP-IDF source code rather than by the applications. Such header files often contain ``private`` or ``esp_private`` in their name or path. Certain components, such as :doc:`hal <../api-guides/hardware-abstraction>` only contain private APIs.
 
 Private APIs may be removed or changed in an incompatible way between minor or patch releases.
 
 .. _api_reference_example_components:
 
-Components in example projects
+Components in Example Projects
 ------------------------------
 
-ESP-IDF examples contain a variety of projects demonstrating usage of ESP-IDF APIs. In order to reduce code duplication in the examples, a few common helpers are defined inside components that are used by multiple examples. This includes components located in :example:`common_components` directory, as well as some of the components located in the examples themselves. These components are not considered to be part of the ESP-IDF API.
+ESP-IDF examples contain a variety of projects demonstrating the usage of ESP-IDF APIs. In order to reduce code duplication in the examples, a few common helpers are defined inside components that are used by multiple examples. This includes components located in :example:`common_components` directory, as well as some of the components located in the examples themselves. These components are not considered to be part of the ESP-IDF API.
 
-It is not recommended to reference these components directly in custom projects (via ``EXTRA_COMPONENT_DIRS`` build system variable), as they may change significantly between ESP-IDF versions. When starting a new project based on an ESP-IDF example, copy both the project and the common components it depends on out of ESP-IDF, and treat the common components as part of the project. Note that the common components are written with examples in mind, and might not include all the error handling required for production applications. Take time to read the code and understand if it applicable to your use case.
+It is not recommended to reference these components directly in custom projects (via ``EXTRA_COMPONENT_DIRS`` build system variable), as they may change significantly between ESP-IDF versions. When starting a new project based on an ESP-IDF example, copy both the project and the common components it depends on out of ESP-IDF, and treat the common components as part of the project. Note that the common components are written with examples in mind, and might not include all the error handling required for production applications. Before using, take time to read the code and understand if it is applicable to your use case.
 
 API Stability
 -------------
 
-ESP-IDF uses `Semantic Versioning <https://semver.org/>`_ as explained in the :ref:`versions page<versioning-scheme>`.
+ESP-IDF uses `Semantic Versioning <https://semver.org/>`_ as explained in the :ref:`Versioning Scheme <versioning-scheme>`.
 
 Minor and bugfix releases of ESP-IDF guarantee compatibility with previous releases. The sections below explain different aspects and limitations to compatibility.
 
-Source level compatibility
+Source-level Compatibility
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-ESP-IDF guarantees source level compatibility of C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-IDF components. Source level compatibility implies that the application can be recompiled with the newer version of ESP-IDF without changes.
+ESP-IDF guarantees source-level compatibility of C functions, structures, enums, type definitions, and preprocessor macros declared in public header files of ESP-IDF components. Source-level compatibility implies that the application source code can be recompiled with the newer version of ESP-IDF without changes.
 
-The following changes are allowed between minor versions and do not break source level compatibility:
+The following changes are allowed between minor versions and do not break source-level compatibility:
 
-* Deprecating functions (using the ``deprecated`` attribute) and header files (using a preprocessor ``#warning``). Deprecations are listed in ESP-IDF relese notes. It is recommended to update the source code to use the newer functions or files that replace the deprecated ones, however this is not mandatory. Deprecated functions and files can be removed in major versions of ESP-IDF.
+* Deprecating functions (using the ``deprecated`` attribute) and header files (using a preprocessor ``#warning``). Deprecations are listed in ESP-IDF release notes. It is recommended to update the source code to use the newer functions or files that replace the deprecated ones, however, this is not mandatory. Deprecated functions and files can be removed from major versions of ESP-IDF.
 * Renaming components, moving source and header files between components — provided that the build system ensures that correct files are still found.
-* Renaming Kconfig options. Kconfig system :ref:`renaming mechanism <configuration-options-compatibility>` ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files and source code.
+* Renaming Kconfig options. Kconfig system's :ref:`backward compatibility <configuration-options-compatibility>` ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files, and source code.
 
-Lack of binary compatibility
+Lack of Binary Compatibility
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-ESP-IDF does not guarantee binary compatibility between releases. This means that if a precompiled library is built with one ESP-IDF version, it is not guaranteed to work the same way with the next minor or bugfix release. The following are the possible changes that keep source level compatibility but not binary compatibility:
+ESP-IDF does not guarantee binary compatibility between releases. This means that if a precompiled library is built with one ESP-IDF version, it is not guaranteed to work the same way with the next minor or bugfix release. The following are the possible changes that keep source-level compatibility but not binary compatibility:
 
 * Changing numerical values for C enum members.
 * Adding new structure members or changing the order of members. See :ref:`api_reference_config_structures` for tips that help ensure compatibility.
 * Replacing an ``extern`` function with a ``static inline`` one with the same signature, or vice versa.
 * Replacing a function-like macro with a compatible C function.
 
-Other exceptions from compatibility
+Other Exceptions from Compatibility
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-While we try to make upgrading to a new ESP-IDF version easy, there are parts of ESP-IDF that may change between minor versions in an incompatible way. We appreciate issue reports about any unintended breaking changes that don't fall into the categories below.
+While we try to make upgrading to a new ESP-IDF version easy, there are parts of ESP-IDF that may change between minor versions in an incompatible way. We appreciate issuing reports about any unintended breaking changes that don't fall into the categories below.
 
 * :ref:`api_reference_private_apis`.
 * :ref:`api_reference_example_components`.
 * Features clearly marked as "beta", "preview", or "experimental".
-* Changes made to mitigate security issues or to replace insecure default behaviors with a secure ones.
-* Features which were never functional. For example, if it was never possible to use a certain function or an enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features which depend on non-functional chip hardware features.
-* Unexpected or undefined behavior (for example, due to missing validation of argument ranges) that is not documented explicitly may be fixed/changed.
+* Changes made to mitigate security issues or to replace insecure default behaviors with secure ones.
+* Features that were never functional. For example, if it was never possible to use a certain function or an enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features that depend on non-functional chip hardware features.
+* Unexpected or undefined behavior that is not documented explicitly may be fixed/changed, such as due to missing validation of argument ranges.
 * Location of :doc:`Kconfig <kconfig>` options in menuconfig.
 * Location and names of example projects.