https://git.ruby-lang.org/ruby.git/commit/?id=20716f64e9

From 20716f64e9287bc71fd8b215e7e92d3a26d2faa6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?=
 <shyouhei@r...>
Date: Fri, 19 Feb 2021 16:03:10 +0900
Subject: include/ruby/internal/intern/select/posix.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/intern/select/posix.h | 65 ++++++++++++++++++++++++++++-
 1 file changed, 64 insertions(+), 1 deletion(-)

diff --git a/include/ruby/internal/intern/select/posix.h b/include/ruby/internal/intern/select/posix.h
index 7a6cd30..bfde159 100644
--- a/include/ruby/internal/intern/select/posix.h
+++ b/include/ruby/internal/intern/select/posix.h
@@ -30,17 +30,41 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/select/posix.h#L30
 # include <unistd.h>            /* for select(2) (archaic UNIX) */
 #endif
 
-#include "ruby/internal/attr/pure.h"
 #include "ruby/internal/attr/const.h"
+#include "ruby/internal/attr/noalias.h"
+#include "ruby/internal/attr/nonnull.h"
+#include "ruby/internal/attr/pure.h"
 
+/**
+ * The data structure which wraps the  fd_set bitmap used by `select(2)`.  This
+ * allows Ruby to use FD sets larger than what has been historically allowed on
+ * modern platforms.
+ *
+ * @internal
+ *
+ * ... but because  this header file is  included only when the  system is with
+ * that "historic restrictions", this is nothing more than an alias of fd_set.
+ */
 typedef fd_set rb_fdset_t;
 
+/** Clears the given ::rb_fdset_t. */
 #define rb_fd_zero   FD_ZERO
+
+/** Sets the given fd to the ::rb_fdset_t. */
 #define rb_fd_set    FD_SET
+
+/** Unsets the given fd from the ::rb_fdset_t. */
 #define rb_fd_clr    FD_CLR
+
+/** Queries if the given fd is in the ::rb_fdset_t. */
 #define rb_fd_isset  FD_ISSET
+
+/** Initialises the :given :rb_fdset_t. */
 #define rb_fd_init   FD_ZERO
+
+/** Waits for multiple file descriptors at once. */
 #define rb_fd_select select
+
 /**@cond INTERNAL_MACRO */
 #define rb_fd_copy  rb_fd_copy
 #define rb_fd_dup   rb_fd_dup
@@ -48,12 +72,32 @@ typedef fd_set rb_fdset_t; https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/select/posix.h#L72
 #define rb_fd_max   rb_fd_max
 /** @endcond */
 
+RBIMPL_ATTR_NONNULL(())
+RBIMPL_ATTR_NOALIAS()
+/**
+ * Destructively overwrites an fdset with another.
+ *
+ * @param[out]  dst   Target fdset.
+ * @param[in]   src   Source fdset.
+ * @param[in]   n     Unused parameter.
+ * @post        `dst` is a copy of `src`.
+ */
 static inline void
 rb_fd_copy(rb_fdset_t *dst, const fd_set *src, int n)
 {
     *dst = *src;
 }
 
+RBIMPL_ATTR_NONNULL(())
+RBIMPL_ATTR_NOALIAS()
+/**
+ * Destructively overwrites an fdset with another.
+ *
+ * @param[out]  dst   Target fdset.
+ * @param[in]   src   Source fdset.
+ * @param[in]   n     Unused parameter.
+ * @post        `dst` is a copy of `src`.
+ */
 static inline void
 rb_fd_dup(rb_fdset_t *dst, const fd_set *src, int n)
 {
@@ -62,6 +106,17 @@ rb_fd_dup(rb_fdset_t *dst, const fd_set *src, int n) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/select/posix.h#L106
 
 RBIMPL_ATTR_PURE()
 /* :TODO: can this function be __attribute__((returns_nonnull)) or not? */
+/**
+ * Raw pointer to `fd_set`.
+ *
+ * @param[in]  f  Target fdset.
+ * @return     Underlying fd_set.
+ *
+ * @internal
+ *
+ * Extension library  must not touch  raw pointers.  It was  a bad idea  to let
+ * them use it.
+ */
 static inline fd_set *
 rb_fd_ptr(rb_fdset_t *f)
 {
@@ -69,14 +124,22 @@ rb_fd_ptr(rb_fdset_t *f) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/select/posix.h#L124
 }
 
 RBIMPL_ATTR_CONST()
+/**
+ * It seems this function has no use.  Maybe just remove?
+ *
+ * @param[in]  f  A set.
+ * @return     Number of file descriptors stored.
+ */
 static inline int
 rb_fd_max(const rb_fdset_t *f)
 {
     return FD_SETSIZE;
 }
 
+/** @cond INTERNAL_MACRO */
 /* :FIXME: What are these?  They don't exist for shibling implementations. */
 #define rb_fd_init_copy(d, s) (*(d) = *(s))
 #define rb_fd_term(f)   ((void)(f))
+/** @endcond */
 
 #endif /* RBIMPL_INTERN_SELECT_POSIX_H */
-- 
cgit v1.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/