Merge branch 'docs/fatfs_add_api_reference' into 'master'

docs(fatfs): Move mentioned APIs to a separate API reference section

Closes IDF-7710

See merge request espressif/esp-idf!24538

components/fatfs/vfs/esp_vfs_fat.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -316,7 +316,7 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
  * @brief Unmount FAT filesystem and release resources acquired using esp_vfs_fat_spiflash_mount_ro
  *
  * @param base_path  path where partition should be registered (e.g. "/spiflash")
- * @param partition_label label of partition to be unmounted
+ * @param partition_label  label of partition to be unmounted
  *
  * @return
  *      - ESP_OK on success
@@ -324,32 +324,49 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
  */
 esp_err_t esp_vfs_fat_spiflash_unmount_ro(const char* base_path, const char* partition_label);
 
+/**
+ * @brief Get information for FATFS partition
+ *
+ * @param base_path  Base path of the partition examined (e.g. "/spiflash")
+ * @param[out] out_total_bytes  Size of the file system
+ * @param[out] out_free_bytes   Free bytes available in the file system
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_STATE if partition not found
+ *      - ESP_FAIL if another FRESULT error (saved in errno)
+ */
+esp_err_t esp_vfs_fat_info(const char* base_path, uint64_t* out_total_bytes, uint64_t* out_free_bytes);
+
+/** @cond */
+/**
+ * @deprecated Please use `esp_vfs_fat_spiflash_mount_rw_wl` instead
+ */
 esp_err_t esp_vfs_fat_spiflash_mount(const char* base_path,
     const char* partition_label,
     const esp_vfs_fat_mount_config_t* mount_config,
     wl_handle_t* wl_handle)
     __attribute__((deprecated("esp_vfs_fat_spiflash_mount is deprecated, please use esp_vfs_fat_spiflash_mount_rw_wl instead")));
+
+/**
+ * @deprecated Please use `esp_vfs_fat_spiflash_unmount_rw_wl` instead
+ */
 esp_err_t esp_vfs_fat_spiflash_unmount(const char* base_path, wl_handle_t wl_handle)
     __attribute__((deprecated("esp_vfs_fat_spiflash_unmount is deprecated, please use esp_vfs_fat_spiflash_unmount_rw_wl instead")));
+
+/**
+ * @deprecated Please use `esp_vfs_fat_spiflash_mount_ro` instead
+ */
 esp_err_t esp_vfs_fat_rawflash_mount(const char* base_path,
     const char* partition_label,
     const esp_vfs_fat_mount_config_t* mount_config)
     __attribute__((deprecated("esp_vfs_fat_rawflash_mount is deprecated, please use esp_vfs_fat_spiflash_mount_ro instead")));
-esp_err_t esp_vfs_fat_rawflash_unmount(const char* base_path, const char* partition_label)
-    __attribute__((deprecated("esp_vfs_fat_rawflash_unmount is deprecated, please use esp_vfs_fat_spiflash_unmount_ro instead")));
 
 /**
- * @brief  Get information for FATFS partition
- *
- * @param base_path  Path where partition should be registered (e.g. "/spiflash")
- * @param[out] out_total_bytes  Size of the file system
- * @param[out] out_free_bytes   Current used bytes in the file system
- * @return
- *      - ESP_OK on success
- *      - ESP_ERR_INVALID_STATE if partition not found
- *      - ESP_FAIL if another FRESULT error (saved in errno)
+ * @deprecated Please use `esp_vfs_fat_spiflash_unmount_ro` instead
  */
-esp_err_t esp_vfs_fat_info(const char* base_path, uint64_t* out_total_bytes, uint64_t* out_free_bytes);
+esp_err_t esp_vfs_fat_rawflash_unmount(const char* base_path, const char* partition_label)
+    __attribute__((deprecated("esp_vfs_fat_rawflash_unmount is deprecated, please use esp_vfs_fat_spiflash_unmount_ro instead")));
+/** @endcond */
 
 #ifdef __cplusplus
 }

docs/en/api-reference/storage/fatfs.rst

@@ -42,10 +42,7 @@ Most applications use the following workflow when working with ``esp_vfs_fat_``
 
 10. Call :cpp:func:`esp_vfs_fat_unregister_path` with the path where the file system is mounted to remove FatFs from VFS, and free the ``FATFS`` structure allocated in Step 1.
 
-The convenience functions ``esp_vfs_fat_sdmmc_mount``, ``esp_vfs_fat_sdspi_mount``, and ``esp_vfs_fat_sdcard_unmount`` wrap the steps described above and also handle SD card initialization. These functions are described in the next section.
-
-.. doxygenfunction:: esp_vfs_fat_register
-.. doxygenfunction:: esp_vfs_fat_unregister_path
+The convenience functions :cpp:func:`esp_vfs_fat_sdmmc_mount`, :cpp:func:`esp_vfs_fat_sdspi_mount`, and :cpp:func:`esp_vfs_fat_sdcard_unmount` wrap the steps described above and also handle SD card initialization. These functions are described in the next section.
 
 
 Using FatFs with VFS and SD Cards
@@ -55,22 +52,12 @@ The header file :component_file:`fatfs/vfs/esp_vfs_fat.h` defines convenience fu
 
 The convenience function :cpp:func:`esp_vfs_fat_sdmmc_unmount` unmounts the filesystem and releases the resources acquired by :cpp:func:`esp_vfs_fat_sdmmc_mount`.
 
-.. doxygenfunction:: esp_vfs_fat_sdmmc_mount
-.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
-.. doxygenfunction:: esp_vfs_fat_sdspi_mount
-.. doxygenstruct:: esp_vfs_fat_mount_config_t
-    :members:
-.. doxygenfunction:: esp_vfs_fat_sdcard_unmount
-
 
 Using FatFs with VFS in Read-Only Mode
 --------------------------------------
 
 The header file :component_file:`fatfs/vfs/esp_vfs_fat.h` also defines the convenience functions :cpp:func:`esp_vfs_fat_spiflash_mount_ro` and :cpp:func:`esp_vfs_fat_spiflash_unmount_ro`. These functions perform Steps 1-3 and 7-9 respectively for read-only FAT partitions. These are particularly helpful for data partitions written only once during factory provisioning, which will not be changed by production application throughout the lifetime of the hardware.
 
-.. doxygenfunction:: esp_vfs_fat_spiflash_mount_ro
-.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_ro
-
 
 FatFS Disk IO Layer
 -------------------
@@ -148,3 +135,9 @@ It is a reverse tool of (:component_file:`fatfsgen.py <fatfs/fatfsgen.py>`), i.e
 Usage::
 
     ./fatfsparse.py [-h] [--wl-layer {detect,enabled,disabled}] fatfs_image.img
+
+
+High-level API Reference
+------------------------
+
+.. include-build-file:: inc/esp_vfs_fat.inc

docs/en/api-reference/storage/wear-levelling.rst

@@ -3,15 +3,15 @@
 See Also
 --------
 
-- :doc:`FAT Filesystem <./fatfs>`
-- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
+- :doc:`./fatfs`
+- :doc:`../../api-guides/partition-tables`
 
 Application Example
 -------------------
 
-An example which combines the wear levelling driver with the FATFS library is provided in the :example:`storage/wear_levelling` directory. This example initializes the wear levelling driver, mounts FATFS partition, as well as writes and reads data from it using POSIX and C library APIs. See the :example_file:`storage/wear_levelling/README.md` file for more information.
+An example that combines the wear levelling driver with the FATFS library is provided in the :example:`storage/wear_levelling` directory. This example initializes the wear levelling driver, mounts FatFs partition, as well as writes and reads data from it using POSIX and C library APIs. See :example_file:`storage/wear_levelling/README.md` for more information.
 
-High-Level API Reference
+High-level API Reference
 ------------------------
 
 Header Files
@@ -19,16 +19,9 @@ Header Files
 
 * :component_file:`fatfs/vfs/esp_vfs_fat.h`
 
-Functions
-^^^^^^^^^
+High-level wear levelling functions :cpp:func:`esp_vfs_fat_spiflash_mount_rw_wl`, :cpp:func:`esp_vfs_fat_spiflash_unmount_rw_wl` and struct :cpp:class:`esp_vfs_fat_mount_config_t` are described in :doc:`./fatfs`.
 
-.. doxygenfunction:: esp_vfs_fat_spiflash_mount_rw_wl
-.. doxygenstruct:: esp_vfs_fat_mount_config_t
-    :members:
-.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_rw_wl
-
-Mid-Level API Reference
+Mid-level API Reference
 -----------------------
 
 .. include-build-file:: inc/wear_levelling.inc
-

docs/sphinx-known-warnings.txt

@@ -23,16 +23,6 @@ mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at api-re
 Declaration is '.. cpp:enum:: esp_mqtt_transport_t'.
 mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/protocols/mqtt:line.
 Declaration is '.. cpp:enum:: esp_mqtt_protocol_ver_t'.
-wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
-Declaration is '.. cpp:struct:: esp_vfs_fat_mount_config_t'.
-wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
-Declaration is '.. cpp:member:: bool format_if_mount_failed'.
-wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
-Declaration is '.. cpp:member:: int max_files'.
-wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
-Declaration is '.. cpp:member:: size_t allocation_unit_size'.
-wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
-Declaration is '.. cpp:member:: bool disk_status_check_enable'.
 esp_heap_trace.inc:line: WARNING: Error when parsing function declaration.
 If the function has no return type:
   Invalid C++ declaration: Expected end of definition or ;. [error at 34]

docs/zh_CN/api-reference/storage/fatfs.rst

@@ -42,10 +42,7 @@ FatFs 与 VFS 配合使用
 
 10. 调用 :cpp:func:`esp_vfs_fat_unregister_path` 并使用文件系统挂载的路径将 FatFs 从 VFS 中移除，并释放步骤 1 中分配的 ``FATFS`` 结构。
 
-便捷函数 ``esp_vfs_fat_sdmmc_mount``、 ``esp_vfs_fat_sdspi_mount`` 和 ``esp_vfs_fat_sdmmc_unmount`` 对上述步骤进行了封装，并加入了对 SD 卡初始化的处理。我们将在下一章节详细介绍以上函数。
-
-.. doxygenfunction:: esp_vfs_fat_register
-.. doxygenfunction:: esp_vfs_fat_unregister_path
+便捷函数 :cpp:func:`esp_vfs_fat_sdmmc_mount`、:cpp:func:`esp_vfs_fat_sdspi_mount` 和 :cpp:func:`esp_vfs_fat_sdcard_unmount` 对上述步骤进行了封装，并加入了对 SD 卡初始化的处理。我们将在下一章节详细介绍以上函数。
 
 
 FatFs 与 VFS 和 SD 卡配合使用
@@ -55,22 +52,12 @@ FatFs 与 VFS 和 SD 卡配合使用
 
 便捷函数 :cpp:func:`esp_vfs_fat_sdmmc_unmount` 用于卸载文件系统并释放从 :cpp:func:`esp_vfs_fat_sdmmc_mount` 函数获取的资源。
 
-.. doxygenfunction:: esp_vfs_fat_sdmmc_mount
-.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
-.. doxygenfunction:: esp_vfs_fat_sdspi_mount
-.. doxygenstruct:: esp_vfs_fat_mount_config_t
-    :members:
-.. doxygenfunction:: esp_vfs_fat_sdcard_unmount
-
 
 FatFs 与 VFS 配合使用（只读模式下）
 --------------------------------------
 
 头文件 :component_file:`fatfs/vfs/esp_vfs_fat.h` 也定义了两个便捷函数 :cpp:func:`esp_vfs_fat_spiflash_mount_ro` 和 :cpp:func:`esp_vfs_fat_spiflash_unmount_ro`。上述两个函数分别对 FAT 只读分区执行步骤 1-3 和步骤 7-9。有些数据分区仅在工厂配置时写入一次，之后在整个硬件生命周期内都不会再有任何改动。利用上述两个函数处理这种数据分区非常方便。
 
-.. doxygenfunction:: esp_vfs_fat_spiflash_mount_ro
-.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_ro
-
 
 FatFs 磁盘 I/O 层
 -------------------
@@ -148,3 +135,9 @@ FatFs 分区分析器
 可以使用::
 
     ./fatfsparse.py [-h] [--wl-layer {detect,enabled,disabled}] fatfs_image.img
+
+
+高级 API 参考
+------------------------
+
+.. include-build-file:: inc/esp_vfs_fat.inc

docs/zh_CN/api-reference/storage/wear-levelling.rst

@@ -3,10 +3,10 @@
 另请参阅
 -----------
 
-- :doc:`FAT 文件系统 <./fatfs>`
-- :doc:`分区表 <../../api-guides/partition-tables>`
+- :doc:`./fatfs`
+- :doc:`../../api-guides/partition-tables`
 
-应用示例  
+应用示例
 -------------------
 
 :example:`storage/wear_levelling` 中提供了一款磨损均衡驱动与 FatFs 库结合使用的示例。该示例初始化磨损均衡驱动，挂载 FAT 文件系统分区，并使用 POSIX（可移植操作系统接口）和 C 库 API 从中写入和读取数据。如需了解更多信息，请参考 :example_file:`storage/wear_levelling/README.md`。
@@ -19,16 +19,9 @@
 
 * :component_file:`fatfs/vfs/esp_vfs_fat.h`
 
-函数
-^^^^^^^^^
-
-.. doxygenfunction:: esp_vfs_fat_spiflash_mount_rw_wl
-.. doxygenstruct:: esp_vfs_fat_mount_config_t
-    :members:
-.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_rw_wl
+有关高级磨损均衡函数 :cpp:func:`esp_vfs_fat_spiflash_mount_rw_wl`、 :cpp:func:`esp_vfs_fat_spiflash_unmount_rw_wl` 和结构体 :cpp:class:`esp_vfs_fat_mount_config_t` 的详细内容，请参见 :doc:`./fatfs`。
 
 中层 API 参考
 -----------------------
 
 .. include-build-file:: inc/wear_levelling.inc
-