From a4fbc53c3d8071ce1534d382b70827669287cff8 Mon Sep 17 00:00:00 2001
From: Troy <andrew998@126.com>
Date: Thu, 28 Mar 2024 21:02:14 +0800
Subject: [PATCH] Add comments for all functions in
 components/libc/posix/io/eventfd/eventfd.c

---
 components/libc/posix/io/eventfd/eventfd.c | 62 +++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/components/libc/posix/io/eventfd/eventfd.c b/components/libc/posix/io/eventfd/eventfd.c
index 81e3a830ae..b42a9b01a0 100644
--- a/components/libc/posix/io/eventfd/eventfd.c
+++ b/components/libc/posix/io/eventfd/eventfd.c
@@ -6,6 +6,7 @@
  * Change Logs:
  * Date           Author       Notes
  * 2023-07-20   zmq810150896   first version
+ * 2024-03-28   TroyMitchell   Add comments for all functions
  */
 
 #include <rtthread.h>
@@ -58,6 +59,11 @@ static const struct dfs_file_ops eventfd_fops =
     .write      = eventfd_write,
 };
 
+/**
+ * @brief   Closes an event file descriptor.
+ * @param   file Pointer to the file descriptor structure.
+ * @return  0 on success, otherwise an error code.
+ */
 static int eventfd_close(struct dfs_file *file)
 {
     struct eventfd_ctx *ctx = file->vnode->data;
@@ -71,6 +77,12 @@ static int eventfd_close(struct dfs_file *file)
     return 0;
 }
 
+/**
+ * @brief   Polls an event file descriptor for events.
+ * @param   file Pointer to the file descriptor structure.
+ * @param   req Pointer to the poll request structure.
+ * @return  Events that occurred on the file descriptor.
+ */
 static int eventfd_poll(struct dfs_file *file, struct rt_pollreq *req)
 {
     struct eventfd_ctx *ctx = (struct eventfd_ctx *)file->vnode->data;
@@ -94,8 +106,23 @@ static int eventfd_poll(struct dfs_file *file, struct rt_pollreq *req)
 }
 
 #ifndef RT_USING_DFS_V2
+/**
+ * @brief   Reads data from an event file descriptor.
+ * @param   file Pointer to the file descriptor structure.
+ * @param   buf Pointer to the buffer to read data into.
+ * @param   count Maximum number of bytes to read.
+ * @return  Number of bytes read on success, otherwise an error code.
+ */
 static ssize_t eventfd_read(struct dfs_file *file, void *buf, size_t count)
 #else
+/**
+ * @brief   Reads data from an event file descriptor.
+ * @param   file Pointer to the file descriptor structure.
+ * @param   buf Pointer to the buffer to read data into.
+ * @param   count Maximum number of bytes to read.
+ * @param   pos Pointer to the file position (not used).
+ * @return  Number of bytes read on success, otherwise an error code.
+ */
 static ssize_t eventfd_read(struct dfs_file *file, void *buf, size_t count, off_t *pos)
 #endif
 {
@@ -146,8 +173,23 @@ static ssize_t eventfd_read(struct dfs_file *file, void *buf, size_t count, off_
 }
 
 #ifndef RT_USING_DFS_V2
+/**
+ * @brief   Writes data to an event file descriptor.
+ * @param   file Pointer to the file descriptor structure.
+ * @param   buf Pointer to the buffer containing data to write.
+ * @param   count Number of bytes to write.
+ * @return  Number of bytes written on success, otherwise an error code.
+ */
 static ssize_t eventfd_write(struct dfs_file *file, const void *buf, size_t count)
 #else
+/**
+ * @brief   Writes data to an event file descriptor.
+ * @param   file Pointer to the file descriptor structure.
+ * @param   buf Pointer to the buffer containing data to write.
+ * @param   count Number of bytes to write.
+ * @param   pos Pointer to the file position (not used).
+ * @return  Number of bytes written on success, otherwise an error code.
+ */
 static ssize_t eventfd_write(struct dfs_file *file, const void *buf, size_t count, off_t *pos)
 #endif
 {
@@ -198,7 +240,13 @@ static ssize_t eventfd_write(struct dfs_file *file, const void *buf, size_t coun
 
     return ret;
 }
-
+/**
+ * @brief   Creates an event file descriptor.
+ * @param   df Pointer to the file descriptor structure.
+ * @param   count Initial value of the event counter.
+ * @param   flags Flags for the event file descriptor.
+ * @return  0 on success, otherwise an error code.
+ */
 static int rt_eventfd_create(struct dfs_file *df, unsigned int count, int flags)
 {
     struct eventfd_ctx *ctx = RT_NULL;
@@ -243,6 +291,12 @@ static int rt_eventfd_create(struct dfs_file *df, unsigned int count, int flags)
     return ret;
 }
 
+/**
+ * @brief   Internal function to create an event file descriptor.
+ * @param   count Initial value of the event counter.
+ * @param   flags Flags for the event file descriptor.
+ * @return  File descriptor on success, otherwise an error code.
+ */
 static int do_eventfd(unsigned int count, int flags)
 {
     struct dfs_file *file;
@@ -279,6 +333,12 @@ static int do_eventfd(unsigned int count, int flags)
     return ret;
 }
 
+/**
+ * @brief   Creates an event file descriptor with the specified count and flags.
+ * @param   count Initial value of the event counter.
+ * @param   flags Flags for the event file descriptor.
+ * @return  File descriptor on success, otherwise an error code.
+ */
 int eventfd(unsigned int count, int flags)
 {
     return do_eventfd(count, flags);