diff --git a/docs/en/api-guides/cplusplus.rst b/docs/en/api-guides/cplusplus.rst index 116f04fe9e..227e146a07 100644 --- a/docs/en/api-guides/cplusplus.rst +++ b/docs/en/api-guides/cplusplus.rst @@ -44,7 +44,7 @@ Multithreading C++ threads, mutexes, and condition variables are supported. C++ threads are built on top of pthreads, which in turn wrap FreeRTOS tasks. -See :example:`cxx/pthread` for an example of creating threads in C++. +See :example:`cxx/pthread` for an example of creating threads in C++. Specifically, this example demonstrates how to use the ESP-pthread component to modify the stack sizes, priorities, names, and core affinities of C++ threads. .. note:: @@ -62,8 +62,7 @@ If an exception is thrown, but there is no ``catch`` block, the program is termi C++ Exceptions should **only** be used for exceptional cases, i.e., something happening unexpectedly and occurs rarely, such as events that happen less frequently than 1/100 times. **Do not** use them for control flow (see also the section about resource usage below). For more information on how to use C++ Exceptions, see the `ISO C++ FAQ `_ and `CPP Core Guidelines `_. -See :example:`cxx/exceptions` for an example of C++ exception handling. - +See :example:`cxx/exceptions` for an example of C++ exception handling. Specifically, this example demonstrates how to enable and use C++ exceptions in {IDF_TARGET_NAME}, with a class that throws an exception from the constructor if the provided argument is equal to 0. C++ Exception Handling and Resource Usage ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -93,8 +92,7 @@ Support for RTTI in ESP-IDF is disabled by default, but can be enabled using :re Enabling this option compiles all C++ files with RTTI support enabled, which allows using ``dynamic_cast`` conversion and ``typeid`` operator. Enabling this option typically increases the binary size by tens of kB. -See :example:`cxx/rtti` for an example of using RTTI in ESP-IDF. - +See :example:`cxx/rtti` for an example of using RTTI in ESP-IDF. Specifically, this example demonstrates how to use the RTTI feature in ESP-IDF, enabling compile time support for RTTI, and showing how to print demangled type names of objects and functions, and how dynamic_cast behaves with objects of two classes derived from a common base class. Developing in C++ ----------------- diff --git a/docs/zh_CN/api-guides/cplusplus.rst b/docs/zh_CN/api-guides/cplusplus.rst index 1bd5ca18fa..5968ef2722 100644 --- a/docs/zh_CN/api-guides/cplusplus.rst +++ b/docs/zh_CN/api-guides/cplusplus.rst @@ -44,7 +44,7 @@ C++ 语言标准 支持 C++ 线程，互斥锁和条件变量。C++ 线程基于 pthread 构建，而 pthread 封装了 FreeRTOS 任务。 -有关在 C++ 中创建线程的示例，请参阅 :example:`cxx/pthread`。 +有关在 C++ 中创建线程的示例，请参阅 :example:`cxx/pthread`。该示例演示了如何使用 ESP-pthread 组件修改 C++ 线程的堆栈大小、优先级、名称和内核亲和性。 .. note:: @@ -62,8 +62,7 @@ ESP-IDF 默认禁用对 C++ 异常处理的支持，可以用 :ref:`CONFIG_COMPI C++ 异常处理应 **仅** 应用于异常情况，即意外情况及罕见情况，如发生频率低于 1% 的事件。**请勿** 将 C++ 异常处理用于流程控制，详情请参阅下文的资源使用部分。有关使用 C++ 异常处理的更多详情，请参阅 `ISO C++ FAQ `_ 和 `CPP 核心指南 `_。 -有关 C++ 异常处理的示例，请参阅 :example:`cxx/exceptions`。 - +有关 C++ 异常处理的示例，请参阅 :example:`cxx/exceptions`。该示例演示了如何在 {IDF_TARGET_NAME} 中启用和使用 C++ 异常，示例中声明了一个类，当提供的参数等于 0 时，这个类会在构造函数中抛出异常。 C++ 异常处理及所需资源 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -93,8 +92,7 @@ ESP-IDF 默认禁用对 RTTI 的支持，可以用 :ref:`CONFIG_COMPILER_CXX_RTT 启用此选项，将以启用了 RTTI 支持的方式编译所有的 C++ 文件，并支持使用 ``dynamic_cast`` 转换和 ``typeid`` 运算符。启用此选项通常会增加几十 KB 的二进制文件大小。 -有关在 ESP-IDF 中使用 RTTI 的示例，请参阅 :example:`cxx/rtti`。 - +有关在 ESP-IDF 中使用 RTTI 的示例，请参阅 :example:`cxx/rtti`。该示例演示了如何在 ESP-IDF 中使用 RTTI 功能，启用编译时对 RTTI 的支持，并展示了如何打印对象和函数的去混淆类型名称，以及 dynamic_cast 在两个继承自同一基类的对象上如何表现。 在 C++ 中进行开发 ----------------- @@ -195,3 +193,12 @@ ESP-IDF 支持 ``iostream`` 功能，但应注意： ------------- 请勿在 C++ 中使用 ``setjmp``/``longjmp``。``longjmp`` 会在不调用任何析构函数的情况下盲目跳出堆栈，容易引起未定义的行为和内存泄漏。请改用 C++ 异常处理，这类程序可以确保正确调用析构函数。如果无法使用 C++ 异常处理，请使用其他替代方案（ ``setjmp``/``longjmp`` 除外），如简单的返回码。 + +应用示例 +-------------------- + +- :example:`cxx/pthread` + +- :example:`cxx/exceptions` 演示了如何在 {IDF_TARGET_NAME} 中启用和使用 C++ 异常。该示例声明了一个类，当提供的参数等于 0 时，这个类会在构造函数中抛出异常。 + +- :example:`cxx/rtti`