chore(bindings/C): resolve doxygen warnings (apache#3572)

bindings/c/Doxyfile

@@ -189,7 +189,6 @@ HTML_COLORSTYLE        = LIGHT
 HTML_COLORSTYLE_HUE    = 220
 HTML_COLORSTYLE_SAT    = 100
 HTML_COLORSTYLE_GAMMA  = 80
-HTML_TIMESTAMP         = NO
 HTML_DYNAMIC_MENUS     = YES
 HTML_DYNAMIC_SECTIONS  = NO
 HTML_INDEX_NUM_ENTRIES = 100
@@ -234,7 +233,6 @@ USE_PDFLATEX           = YES
 LATEX_BATCHMODE        = NO
 LATEX_HIDE_INDICES     = NO
 LATEX_BIB_STYLE        = plain
-LATEX_TIMESTAMP        = NO
 GENERATE_RTF           = NO
 RTF_OUTPUT             = rtf
 COMPACT_RTF            = NO
@@ -289,4 +287,4 @@ MAX_DOT_GRAPH_DEPTH    = 0
 DOT_MULTI_TARGETS      = NO
 GENERATE_LEGEND        = YES
 DOT_CLEANUP            = YES
-HTML_EXTRA_STYLESHEET  = ./docs/doxygen-awesome.css
+HTML_EXTRA_STYLESHEET  = ./docs/doxygen-awesome.css

bindings/c/include/opendal.h

@@ -728,7 +728,7 @@ void opendal_metadata_free(struct opendal_metadata *ptr);
  * # Example
  * ```C
  * // ... previously you wrote "Hello, World!" to path "/testpath"
- * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * opendal_result_stat s = opendal_operator_stat(op, "/testpath");
  * assert(s.error == NULL);
  *
  * opendal_metadata *meta = s.meta;
@@ -743,7 +743,7 @@ uint64_t opendal_metadata_content_length(const struct opendal_metadata *self);
  * # Example
  * ```C
  * // ... previously you wrote "Hello, World!" to path "/testpath"
- * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * opendal_result_stat s = opendal_operator_stat(op, "/testpath");
  * assert(s.error == NULL);
  *
  * opendal_metadata *meta = s.meta;
@@ -758,7 +758,7 @@ bool opendal_metadata_is_file(const struct opendal_metadata *self);
  * # Example
  * ```C
  * // ... previously you wrote "Hello, World!" to path "/testpath"
- * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * opendal_result_stat s = opendal_operator_stat(op, "/testpath");
  * assert(s.error == NULL);
  *
  * opendal_metadata *meta = s.meta;
@@ -778,7 +778,7 @@ bool opendal_metadata_is_dir(const struct opendal_metadata *self);
  * # Example
  * ```C
  * // ... previously you wrote "Hello, World!" to path "/testpath"
- * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * opendal_result_stat s = opendal_operator_stat(op, "/testpath");
  * assert(s.error == NULL);
  *
  * opendal_metadata *meta = s.meta;
@@ -797,11 +797,11 @@ int64_t opendal_metadata_last_modified_ms(const struct opendal_metadata *self);
  * # Example
  *
  * ```C
- * opendal_operator *ptr = opendal_operator_new("fs", NULL);
- * // ... use this ptr, maybe some reads and writes
+ * opendal_operator *op = opendal_operator_new("fs", NULL);
+ * // ... use this op, maybe some reads and writes
  *
  * // free this operator
- * opendal_operator_free(ptr);
+ * opendal_operator_free(op);
  * ```
  */
 void opendal_operator_free(const struct opendal_operator *op);
@@ -857,7 +857,7 @@ struct opendal_result_operator_new opendal_operator_new(const char *scheme,
  * \note It is important to notice that the `bytes` that is passes in will be consumed by this
  *       function. Therefore, you should not use the `bytes` after this function returns.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param path The designated path you want to write your bytes in
  * @param bytes The opendal_byte typed bytes to be written
  * @see opendal_operator
@@ -869,14 +869,14 @@ struct opendal_result_operator_new opendal_operator_new(const char *scheme,
  *
  * Following is an example
  * ```C
- * //...prepare your opendal_operator, named ptr for example
+ * //...prepare your opendal_operator, named op for example
  *
  * // prepare your data
  * char* data = "Hello, World!";
  * opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
  *
  * // now you can write!
- * opendal_error *err = opendal_operator_write(ptr, "/testpath", bytes);
+ * opendal_error *err = opendal_operator_write(op, "/testpath", bytes);
  *
  * // Assert that this succeeds
  * assert(err == NULL);
@@ -903,7 +903,7 @@ struct opendal_error *opendal_operator_write(const struct opendal_operator *op,
  *
  * Read the data out from `path` blockingly by operator.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param path The path you want to read the data out
  * @see opendal_operator
  * @see opendal_result_read
@@ -921,7 +921,7 @@ struct opendal_error *opendal_operator_write(const struct opendal_operator *op,
  * ```C
  * // ... you have write "Hello, World!" to path "/testpath"
  *
- * opendal_result_read r = opendal_operator_read(ptr, "testpath");
+ * opendal_result_read r = opendal_operator_read(op, "testpath");
  * assert(r.error == NULL);
  *
  * opendal_bytes *bytes = r.data;
@@ -947,10 +947,8 @@ struct opendal_result_read opendal_operator_read(const struct opendal_operator *
  * Read the data out from `path` blockingly by operator, returns
  * an opendal_result_read with error code.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param path The path you want to read the data out
- * @param buffer The buffer you want to read the data into
- * @param buffer_len The length of the buffer
  * @see opendal_operator
  * @see opendal_result_read
  * @see opendal_code
@@ -990,7 +988,7 @@ struct opendal_result_operator_reader opendal_operator_reader(const struct opend
  * Delete the object in `path` blockingly by `op_ptr`.
  * Error is NULL if successful, otherwise it contains the error code and error message.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param path The designated path you want to delete
  * @see opendal_operator
  * @see opendal_error
@@ -1000,17 +998,17 @@ struct opendal_result_operator_reader opendal_operator_reader(const struct opend
  *
  * Following is an example
  * ```C
- * //...prepare your opendal_operator, named ptr for example
+ * //...prepare your opendal_operator, named op for example
  *
  * // prepare your data
  * char* data = "Hello, World!";
  * opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
- * opendal_error *error = opendal_operator_write(ptr, "/testpath", bytes);
+ * opendal_error *error = opendal_operator_write(op, "/testpath", bytes);
  *
  * assert(error == NULL);
  *
  * // now you can delete!
- * opendal_error *error = opendal_operator_delete(ptr, "/testpath");
+ * opendal_error *error = opendal_operator_delete(op, "/testpath");
  *
  * // Assert that this succeeds
  * assert(error == NULL);
@@ -1035,7 +1033,7 @@ struct opendal_error *opendal_operator_delete(const struct opendal_operator *op,
  * the error should be a nullptr. Otherwise, the field `is_exist`
  * is filled with false, and the error is set
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param path The path you want to check existence
  * @see opendal_operator
  * @see opendal_result_is_exist
@@ -1047,12 +1045,12 @@ struct opendal_error *opendal_operator_delete(const struct opendal_operator *op,
  *
  * ```C
  * // .. you previously wrote some data to path "/mytest/obj"
- * opendal_result_is_exist e = opendal_operator_is_exist(ptr, "/mytest/obj");
+ * opendal_result_is_exist e = opendal_operator_is_exist(op, "/mytest/obj");
  * assert(e.error == NULL);
  * assert(e.is_exist);
  *
  * // but you previously did **not** write any data to path "/yourtest/obj"
- * opendal_result_is_exist e = opendal_operator_is_exist(ptr, "/yourtest/obj");
+ * opendal_result_is_exist e = opendal_operator_is_exist(op, "/yourtest/obj");
  * assert(e.error == NULL);
  * assert(!e.is_exist);
  * ```
@@ -1075,7 +1073,7 @@ struct opendal_result_is_exist opendal_operator_is_exist(const struct opendal_op
  *
  * Error is NULL if successful, otherwise it contains the error code and error message.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param path The path you want to stat
  * @see opendal_operator
  * @see opendal_result_stat
@@ -1089,7 +1087,7 @@ struct opendal_result_is_exist opendal_operator_is_exist(const struct opendal_op
  *
  * ```C
  * // ... previously you wrote "Hello, World!" to path "/testpath"
- * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * opendal_result_stat s = opendal_operator_stat(op, "/testpath");
  * assert(s.error == NULL);
  *
  * const opendal_metadata *meta = s.meta;
@@ -1118,7 +1116,7 @@ struct opendal_result_stat opendal_operator_stat(const struct opendal_operator *
  * opendal_lister. Users should call opendal_lister_next() on the
  * lister.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param path The designated path you want to list
  * @see opendal_lister
  * @return Returns opendal_result_list, containing a lister and an opendal_error.
@@ -1131,8 +1129,8 @@ struct opendal_result_stat opendal_operator_stat(const struct opendal_operator *
  * Following is an example
  * ```C
  * // You have written some data into some files path "root/dir1"
- * // Your opendal_operator was called ptr
- * opendal_result_list l = opendal_operator_list(ptr, "root/dir1");
+ * // Your opendal_operator was called op
+ * opendal_result_list l = opendal_operator_list(op, "root/dir1");
  * assert(l.error == ERROR);
  *
  * opendal_lister *lister = l.lister;
@@ -1170,7 +1168,7 @@ struct opendal_result_list opendal_operator_list(const struct opendal_operator *
  * Create the directory in `path` blockingly by `op_ptr`.
  * Error is NULL if successful, otherwise it contains the error code and error message.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param path The designated directory you want to create
  * @see opendal_operator
  * @see opendal_error
@@ -1180,10 +1178,10 @@ struct opendal_result_list opendal_operator_list(const struct opendal_operator *
  *
  * Following is an example
  * ```C
- * //...prepare your opendal_operator, named ptr for example
+ * //...prepare your opendal_operator, named op for example
  *
  * // create your directory
- * opendal_error *error = opendal_operator_create_dir(ptr, "/testdir/");
+ * opendal_error *error = opendal_operator_create_dir(op, "/testdir/");
  *
  * // Assert that this succeeds
  * assert(error == NULL);
@@ -1208,7 +1206,7 @@ struct opendal_error *opendal_operator_create_dir(const struct opendal_operator
  * Rename the object in `src` to `dest` blockingly by `op`.
  * Error is NULL if successful, otherwise it contains the error code and error message.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param src The designated source path you want to rename
  * @param dest The designated destination path you want to rename
  * @see opendal_operator
@@ -1219,17 +1217,17 @@ struct opendal_error *opendal_operator_create_dir(const struct opendal_operator
  *
  * Following is an example
  * ```C
- * //...prepare your opendal_operator, named ptr for example
+ * //...prepare your opendal_operator, named op for example
  *
  * // prepare your data
  * char* data = "Hello, World!";
  * opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
- * opendal_error *error = opendal_operator_write(ptr, "/testpath", bytes);
+ * opendal_error *error = opendal_operator_write(op, "/testpath", bytes);
  *
  * assert(error == NULL);
  *
  * // now you can renmae!
- * opendal_error *error = opendal_operator_rename(ptr, "/testpath", "/testpath2");
+ * opendal_error *error = opendal_operator_rename(op, "/testpath", "/testpath2");
  *
  * // Assert that this succeeds
  * assert(error == NULL);
@@ -1255,7 +1253,7 @@ struct opendal_error *opendal_operator_rename(const struct opendal_operator *op,
  * Copy the object in `src` to `dest` blockingly by `op`.
  * Error is NULL if successful, otherwise it contains the error code and error message.
  *
- * @param ptr The opendal_operator created previously
+ * @param op The opendal_operator created previously
  * @param src The designated source path you want to copy
  * @param dest The designated destination path you want to copy
  * @see opendal_operator
@@ -1266,17 +1264,17 @@ struct opendal_error *opendal_operator_rename(const struct opendal_operator *op,
  *
  * Following is an example
  * ```C
- * //...prepare your opendal_operator, named ptr for example
+ * //...prepare your opendal_operator, named op for example
  *
  * // prepare your data
  * char* data = "Hello, World!";
  * opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
- * opendal_error *error = opendal_operator_write(ptr, "/testpath", bytes);
+ * opendal_error *error = opendal_operator_write(op, "/testpath", bytes);
  *
  * assert(error == NULL);
  *
  * // now you can renmae!
- * opendal_error *error = opendal_operator_copy(ptr, "/testpath", "/testpath2");
+ * opendal_error *error = opendal_operator_copy(op, "/testpath", "/testpath2");
  *
  * // Assert that this succeeds
  * assert(error == NULL);

bindings/c/src/metadata.rs

@@ -56,7 +56,7 @@ impl opendal_metadata {
     /// # Example
     /// ```C
     /// // ... previously you wrote "Hello, World!" to path "/testpath"
-    /// opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+    /// opendal_result_stat s = opendal_operator_stat(op, "/testpath");
     /// assert(s.error == NULL);
     ///
     /// opendal_metadata *meta = s.meta;
@@ -74,7 +74,7 @@ impl opendal_metadata {
     /// # Example
     /// ```C
     /// // ... previously you wrote "Hello, World!" to path "/testpath"
-    /// opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+    /// opendal_result_stat s = opendal_operator_stat(op, "/testpath");
     /// assert(s.error == NULL);
     ///
     /// opendal_metadata *meta = s.meta;
@@ -94,7 +94,7 @@ impl opendal_metadata {
     /// # Example
     /// ```C
     /// // ... previously you wrote "Hello, World!" to path "/testpath"
-    /// opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+    /// opendal_result_stat s = opendal_operator_stat(op, "/testpath");
     /// assert(s.error == NULL);
     ///
     /// opendal_metadata *meta = s.meta;
@@ -117,7 +117,7 @@ impl opendal_metadata {
     /// # Example
     /// ```C
     /// // ... previously you wrote "Hello, World!" to path "/testpath"
-    /// opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+    /// opendal_result_stat s = opendal_operator_stat(op, "/testpath");
     /// assert(s.error == NULL);
     ///
     /// opendal_metadata *meta = s.meta;