From df9d1cc5d47150843942d961927ebd77392769ca Mon Sep 17 00:00:00 2001 From: liying Date: Tue, 6 Nov 2018 18:40:17 +0800 Subject: [PATCH] doc:update_creating_example_cn --- docs/en/contribute/creating-examples.rst | 2 +- docs/zh_CN/contribute/creating-examples.rst | 32 ++++++++++----------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/en/contribute/creating-examples.rst b/docs/en/contribute/creating-examples.rst index eb8132b80..0904d3e43 100644 --- a/docs/en/contribute/creating-examples.rst +++ b/docs/en/contribute/creating-examples.rst @@ -10,7 +10,7 @@ Structure - If the example has additional functionality, split it logically into separate C or C++ source files under ``main`` and place a corresponding header file in the same directory. - If the example has a lot of additional functionality, consider adding a ``components`` directory to the example project and make some example-specific components with library functionality. Only do this if the components are specific to the example, if they're generic or common functionality then they should be added to ESP-IDF itself. - The example should have a ``README.md`` file. Use the :idf_file:`template example README ` and adapt it for your particular example. -- Examples should have an ``example_test.py`` file for running an automated example test. If submitting a GitHub Pull Request which includes an example, it's OK not to include this file initially. The details can be discussed as part of the PR. +- Examples should have an ``example_test.py`` file for running an automated example test. If submitting a GitHub Pull Request which includes an example, it's OK not to include this file initially. The details can be discussed as part of the `Pull Request `_. General Guidelines ------------------ diff --git a/docs/zh_CN/contribute/creating-examples.rst b/docs/zh_CN/contribute/creating-examples.rst index 117d41f18..fa9ad0fca 100644 --- a/docs/zh_CN/contribute/creating-examples.rst +++ b/docs/zh_CN/contribute/creating-examples.rst @@ -1,16 +1,16 @@ 创建示例项目 ============ -每个 ESP-IDF 的示例都是一个完整的项目，其他人可以复制并修改代码以解决他们自己的问题。请注意，示例项目的主要目的是为了展示 ESP-IDF 的功能。 +每个 ESP-IDF 的示例都是一个完整的项目，其他人可以将示例复制至本地，并根据实际情况进行一定修改。请注意，示例项目主要是为了展示 ESP-IDF 的功能。 示例项目结构 ------------ - ``main`` 目录需要包含一个名为 ``(something)_example_main.c`` 的源文件，里面包含示例项目的主要功能。 -- 如果该示例项目的子任务比较多，请根据逻辑将其拆分为 ``main`` 目录下的多个 C 或者 C++ 源文件，并将相应的头文件放在同一目录下。 -- 如果该示例项目具有多种功能，可以考虑在项目中增加一个 ``components`` 子目录，以组件的形式为示例项目提供服务。如果该组件提供的功能具有一定的通用性和完整性，则应该将它们添加到 ESP-IDF 的 ``components`` 目录中，使其成为 ESP-IDF 的一部分。 -- 示例项目需要包含一个 ``README.md`` 文件，建议在 :idf_file:`示例项目 README 模板 ` 的基础上进行修改，使其适配你的项目。 -- 示例项目需要包含一个 ``example_test.py`` 文件，用于自动化测试本示例项目。如果在 GitHub Pull Request 上初次提交示例项目，可以先不包含这个脚本文件，该文件的实现细节可以在后续的 PR 中进行讨论。 +- 如果该示例项目的子任务比较多，请根据逻辑将其拆分为 ``main`` 目录下的多个 C 或者 C++ 源文件，并将对应的头文件也放在同一目录下。 +- 如果该示例项目具有多种功能，可以考虑在项目中增加一个 ``components`` 子目录，通过库功能，将示例项目的不同功能划分为不同的组件。注意，如果该组件提供的功能相对完整，且具有一定的通用性，则应该将它们添加到 ESP-IDF 的 ``components`` 目录中，使其成为 ESP-IDF 的一部分。 +- 示例项目需要包含一个 ``README.md`` 文件，建议使用 :idf_file:`示例项目 README 模板 ` ，并根据项目实际情况进行修改。 +- 示例项目需要包含一个 ``example_test.py`` 文件，用于进行自动化测试。如果在 GitHub 上初次提交 Pull Request 时，可以先不包含这个脚本文件。具体细节，请见有关 `Pull Request `_ 的相关内容。 一般准则 -------- @@ -20,15 +20,15 @@ 检查清单 -------- -提交示例项目之前需要检查的清单如下： +提交一个新的示例项目之前，需要检查以下内容： -- 示例项目的名字（在 ``Makefile`` 和 ``README.md`` 中）使用单词 ``example`` 而不是 “demo”，“test” 类似的单词。 -- 示例项目的目的只能有一个，如果有多个，请将它们拆分为两个或更多示例项目。 -- 示例项目中需要包含一个 ``README.md`` 文件，建议使用 :idf_file:`示例项目 README 模板 `。 -- 示例项目中的函数和变量的命令要遵循 :ref:`命名规范 ` 中的要求。 -- 示例项目中的所有代码结构良好，并且关键代码有详细注释。 -- 示例项目中清除不必要的代码（旧的调试日志，注释掉的代码等）。 -- 示例项目中用使用的选项（比如网络名称，地址等）不应该被硬编码，尽可能地使用可配置项或者宏定义和常量。 -- 配置项在 ``KConfig.projbuild`` 文件中提供，该文件中包含有名为 “Example Configuration” 的菜单。查看现有的示例项目以了解如何实现该操作。 -- 所有的原始代码都需要在文件开头指定许可证和免责声明，表示它 ``in the public domain CC0``。或者，示例项目可以在 ``Apache License 2.0`` 协议下获得许可。请查看已有的示例项目然后做相应的修改。 -- 任何改动的或直接使用的第三方代码都需要在文件开头声明其原始的许可证，且该许可证必须要与 ``Apache License 2.0`` 协议兼容。 +- 示例项目的名字（包括 ``Makefile`` 和 ``README.md`` 中）应使用 ``example``，而不要写 “demo”，“test” 等词汇。 +- 每个示例项目只能有一个主要功能。如果某个示例项目有多个主要功能，请将其拆分为两个或更多示例项目。 +- 每个示例项目应包含一个 ``README.md`` 文件，建议使用 :idf_file:`示例项目 README 模板 `。 +- 示例项目中的函数和变量的命令要遵循 :ref:`命名规范 ` 中的要求。对于仅在示例项目源文件中使用的非静态变量/函数，请使用 ``example`` 或其他类似的前缀。 +- 示例项目中的所有代码结构良好，关键代码要有详细注释。 +- 示例项目中所有不必要的代码（旧的调试日志，注释掉的代码等）都必须清除掉。 +- 示例项目中使用的选项（比如网络名称，地址等）不得直接硬编码，应尽可能地使用配置项，或者定义为宏或常量。 +- 配置项可见 ``KConfig.projbuild`` 文件，该文件中包含一个名为 “Example Configuration” 的菜单。具体情况，请查看现有示例项目。 +- 所有的源代码都需要在文件开头指定许可信息（表示该代码是 ``in the public domain CC0``）和免责声明。或者，源代码也可以应用 ``Apache License 2.0`` 许可条款。请查看现有示例项目的许可信息和免责声明，并根据实际情况进行修改。 +- 任何第三方代码（无论是直接使用，还是进行了一些改进）均应保留原始代码中的许可信息，且这些代码的许可必须兼容 ``Apache License 2.0`` 协议。 \ No newline at end of file