[DOC] Unify Doxygen formats (#10285)

class.c

@@ -225,14 +225,14 @@ rb_class_detach_module_subclasses(VALUE klass)
 /**
  * Allocates a struct RClass for a new class.
  *
- * \param flags     initial value for basic.flags of the returned class.
- * \param klass     the class of the returned class.
- * \return          an uninitialized Class object.
- * \pre  \p klass must refer \c Class class or an ancestor of Class.
- * \pre  \code (flags | T_CLASS) != 0  \endcode
- * \post the returned class can safely be \c #initialize 'd.
- *
- * \note this function is not Class#allocate.
+ * @param flags     initial value for basic.flags of the returned class.
+ * @param klass     the class of the returned class.
+ * @return          an uninitialized Class object.
+ * @pre  `klass` must refer `Class` class or an ancestor of Class.
+ * @pre  `(flags | T_CLASS) != 0`
+ * @post the returned class can safely be `#initialize` 'd.
+ *
+ * @note this function is not Class#allocate.
  */
 static VALUE
 class_alloc(VALUE flags, VALUE klass)
@@ -267,14 +267,14 @@ RCLASS_M_TBL_INIT(VALUE c)
     RCLASS_M_TBL(c) = rb_id_table_create(0);
 }
 
-/*!
+/**
  * A utility function that wraps class_alloc.
  *
  * allocates a class and initializes safely.
- * \param super     a class from which the new class derives.
- * \return          a class object.
- * \pre  \a super must be a class.
- * \post the metaclass of the new class is Class.
+ * @param super     a class from which the new class derives.
+ * @return          a class object.
+ * @pre  `super` must be a class.
+ * @post the metaclass of the new class is Class.
  */
 VALUE
 rb_class_boot(VALUE super)
@@ -732,7 +732,7 @@ rb_singleton_class_internal_p(VALUE sklass)
             !rb_singleton_class_has_metaclass_p(sklass));
 }
 
-/*!
+/**
  * whether k has a metaclass
  * @retval 1 if \a k has a metaclass
  * @retval 0 otherwise
@@ -741,25 +741,25 @@ rb_singleton_class_internal_p(VALUE sklass)
     (FL_TEST(METACLASS_OF(k), FL_SINGLETON) && \
      rb_singleton_class_has_metaclass_p(k))
 
-/*!
- * ensures \a klass belongs to its own eigenclass.
- * @return the eigenclass of \a klass
- * @post \a klass belongs to the returned eigenclass.
- *       i.e. the attached object of the eigenclass is \a klass.
+/**
+ * ensures `klass` belongs to its own eigenclass.
+ * @return the eigenclass of `klass`
+ * @post `klass` belongs to the returned eigenclass.
+ *       i.e. the attached object of the eigenclass is `klass`.
  * @note this macro creates a new eigenclass if necessary.
  */
 #define ENSURE_EIGENCLASS(klass) \
     (HAVE_METACLASS_P(klass) ? METACLASS_OF(klass) : make_metaclass(klass))
 
 
-/*!
- * Creates a metaclass of \a klass
- * \param klass     a class
- * \return          created metaclass for the class
- * \pre \a klass is a Class object
- * \pre \a klass has no singleton class.
- * \post the class of \a klass is the returned class.
- * \post the returned class is meta^(n+1)-class when \a klass is a meta^(n)-klass for n >= 0
+/**
+ * Creates a metaclass of `klass`
+ * @param klass     a class
+ * @return          created metaclass for the class
+ * @pre `klass` is a Class object
+ * @pre `klass` has no singleton class.
+ * @post the class of `klass` is the returned class.
+ * @post the returned class is meta^(n+1)-class when `klass` is a meta^(n)-klass for n >= 0
  */
 static inline VALUE
 make_metaclass(VALUE klass)
@@ -790,11 +790,11 @@ make_metaclass(VALUE klass)
     return metaclass;
 }
 
-/*!
- * Creates a singleton class for \a obj.
- * \pre \a obj must not a immediate nor a special const.
- * \pre \a obj must not a Class object.
- * \pre \a obj has no singleton class.
+/**
+ * Creates a singleton class for `obj`.
+ * @pre `obj` must not be an immediate nor a special const.
+ * @pre `obj` must not be a Class object.
+ * @pre `obj` has no singleton class.
  */
 static inline VALUE
 make_singleton_class(VALUE obj)
@@ -925,15 +925,15 @@ Init_class_hierarchy(void)
 }
 
 
-/*!
- * \internal
+/**
+ * @internal
  * Creates a new *singleton class* for an object.
  *
- * \pre \a obj has no singleton class.
- * \note DO NOT USE the function in an extension libraries. Use \ref rb_singleton_class.
- * \param obj     An object.
- * \param unused  ignored.
- * \return        The singleton class of the object.
+ * @pre `obj` has no singleton class.
+ * @note DO NOT USE the function in an extension libraries. Use @ref rb_singleton_class.
+ * @param obj     An object.
+ * @param unused  ignored.
+ * @return        The singleton class of the object.
  */
 VALUE
 rb_make_metaclass(VALUE obj, VALUE unused)
@@ -959,13 +959,13 @@ rb_define_class_id(ID id, VALUE super)
 }
 
 
-/*!
+/**
  * Calls Class#inherited.
- * \param super  A class which will be called #inherited.
+ * @param super  A class which will be called #inherited.
  *               NULL means Object class.
- * \param klass  A Class object which derived from \a super
- * \return the value \c Class#inherited's returns
- * \pre Each of \a super and \a klass must be a \c Class object.
+ * @param klass  A Class object which derived from `super`
+ * @return the value `Class#inherited` returns
+ * @pre Each of `super` and `klass` must be a `Class` object.
  */
 VALUE
 rb_class_inherited(VALUE super, VALUE klass)
@@ -2214,13 +2214,13 @@ rb_special_singleton_class(VALUE obj)
     return special_singleton_class_of(obj);
 }
 
-/*!
- * \internal
- * Returns the singleton class of \a obj. Creates it if necessary.
+/**
+ * @internal
+ * Returns the singleton class of `obj`. Creates it if necessary.
  *
- * \note DO NOT expose the returned singleton class to
+ * @note DO NOT expose the returned singleton class to
  *       outside of class.c.
- *       Use \ref rb_singleton_class instead for
+ *       Use @ref rb_singleton_class instead for
  *       consistency of the metaclass hierarchy.
  */
 static VALUE
@@ -2276,12 +2276,12 @@ rb_freeze_singleton_class(VALUE x)
     }
 }
 
-/*!
- * Returns the singleton class of \a obj, or nil if obj is not a
+/**
+ * Returns the singleton class of `obj`, or nil if obj is not a
  * singleton object.
  *
- * \param obj an arbitrary object.
- * \return the singleton class or nil.
+ * @param obj an arbitrary object.
+ * @return the singleton class or nil.
  */
 VALUE
 rb_singleton_class_get(VALUE obj)

eval.c

@@ -410,11 +410,11 @@ rb_mod_s_constants(int argc, VALUE *argv, VALUE mod)
     return rb_const_list(data);
 }
 
-/*!
- * Asserts that \a klass is not a frozen class.
- * \param[in] klass a \c Module object
- * \exception RuntimeError if \a klass is not a class or frozen.
- * \ingroup class
+/**
+ * Asserts that `klass` is not a frozen class.
+ * @param[in] klass a `Module` object
+ * @exception RuntimeError if `klass` is not a class or frozen.
+ * @ingroup class
  */
 void
 rb_class_modify_check(VALUE klass)
@@ -666,12 +666,12 @@ rb_exc_exception(VALUE mesg, enum ruby_tag_type tag, VALUE cause)
     rb_longjmp(GET_EC(), tag, mesg, cause);
 }
 
-/*!
+/**
  * Raises an exception in the current thread.
- * \param[in] mesg an Exception class or an \c Exception object.
- * \exception always raises an instance of the given exception class or
- *   the given \c Exception object.
- * \ingroup exception
+ * @param[in] mesg an Exception class or an `Exception` object.
+ * @exception always raises an instance of the given exception class or
+ *   the given `Exception` object.
+ * @ingroup exception
  */
 void
 rb_exc_raise(VALUE mesg)

internal/sanitizers.h

@@ -95,7 +95,7 @@
 # define VALGRIND_MAKE_MEM_UNDEFINED(p, n) 0
 #endif
 
-/*!
+/**
  * This function asserts that a (continuous) memory region from ptr to size
  * being "poisoned".  Both read / write access to such memory region are
  * prohibited until properly unpoisoned.  The region must be previously
@@ -105,8 +105,8 @@
  * region to reuse later: poison when you keep it unused, and unpoison when you
  * reuse.
  *
- * \param[in]  ptr   pointer to the beginning of the memory region to poison.
- * \param[in]  size  the length of the memory region to poison.
+ * @param[in]  ptr   pointer to the beginning of the memory region to poison.
+ * @param[in]  size  the length of the memory region to poison.
  */
 static inline void
 asan_poison_memory_region(const volatile void *ptr, size_t size)
@@ -115,10 +115,10 @@ asan_poison_memory_region(const volatile void *ptr, size_t size)
     __asan_poison_memory_region(ptr, size);
 }
 
-/*!
+/**
  * This is a variant of asan_poison_memory_region that takes a VALUE.
  *
- * \param[in]  obj   target object.
+ * @param[in]  obj   target object.
  */
 static inline void
 asan_poison_object(VALUE obj)
@@ -135,12 +135,12 @@ asan_poison_object(VALUE obj)
 #define asan_poison_object_if(ptr, obj) ((void)(ptr), (void)(obj))
 #endif
 
-/*!
+/**
  * This function predicates if the given object is fully addressable or not.
  *
- * \param[in]  obj        target object.
- * \retval     0          the given object is fully addressable.
- * \retval     otherwise  pointer to first such byte who is poisoned.
+ * @param[in]  obj        target object.
+ * @retval     0          the given object is fully addressable.
+ * @retval     otherwise  pointer to first such byte who is poisoned.
  */
 static inline void *
 asan_poisoned_object_p(VALUE obj)
@@ -149,7 +149,7 @@ asan_poisoned_object_p(VALUE obj)
     return __asan_region_is_poisoned(ptr, SIZEOF_VALUE);
 }
 
-/*!
+/**
  * This function asserts that a (formally poisoned) memory region from ptr to
  * size is now addressable.  Write access to such memory region gets allowed.
  * However read access might or might not be possible depending on situations,
@@ -160,9 +160,9 @@ asan_poisoned_object_p(VALUE obj)
  * the other hand, that memory region is fully defined and can be read
  * immediately.
  *
- * \param[in]  ptr       pointer to the beginning of the memory region to unpoison.
- * \param[in]  size      the length of the memory region.
- * \param[in]  malloc_p  if the memory region is like a malloc's return value or not.
+ * @param[in]  ptr       pointer to the beginning of the memory region to unpoison.
+ * @param[in]  size      the length of the memory region.
+ * @param[in]  malloc_p  if the memory region is like a malloc's return value or not.
  */
 static inline void
 asan_unpoison_memory_region(const volatile void *ptr, size_t size, bool malloc_p)
@@ -176,11 +176,11 @@ asan_unpoison_memory_region(const volatile void *ptr, size_t size, bool malloc_p
     }
 }
 
-/*!
+/**
  * This is a variant of asan_unpoison_memory_region that takes a VALUE.
  *
- * \param[in]  obj       target object.
- * \param[in]  malloc_p  if the memory region is like a malloc's return value or not.
+ * @param[in]  obj       target object.
+ * @param[in]  malloc_p  if the memory region is like a malloc's return value or not.
  */
 static inline void
 asan_unpoison_object(VALUE obj, bool newobj_p)
@@ -207,7 +207,7 @@ asan_poison_object_restore(VALUE obj, void *ptr)
 }
 
 
-/*!
+/**
  * Checks if the given pointer is on an ASAN fake stack. If so, it returns the
  * address this variable has on the real frame; if not, it returns the origin
  * address unmodified.
@@ -219,8 +219,8 @@ asan_poison_object_restore(VALUE obj, void *ptr)
  * n.b. - this only works for addresses passed in from local variables on the same
  * thread, because the ASAN fake stacks are threadlocal.
  *
- * \param[in] slot  the address of some local variable
- * \retval          a pointer to something from that frame on the _real_ machine stack
+ * @param[in] slot  the address of some local variable
+ * @retval          a pointer to something from that frame on the _real_ machine stack
  */
 static inline void *
 asan_get_real_stack_addr(void* slot)
@@ -230,18 +230,18 @@ asan_get_real_stack_addr(void* slot)
     return addr ? addr : slot;
 }
 
-/*!
+/**
  * Gets the current thread's fake stack handle, which can be passed into get_fake_stack_extents
  *
- * \retval An opaque value which can be passed to asan_get_fake_stack_extents
+ * @retval An opaque value which can be passed to asan_get_fake_stack_extents
  */
 static inline void *
 asan_get_thread_fake_stack_handle(void)
 {
     return __asan_get_current_fake_stack();
 }
 
-/*!
+/**
  * Checks if the given VALUE _actually_ represents a pointer to an ASAN fake stack.
  *
  * If the given slot _is_ actually a reference to an ASAN fake stack, and that fake stack
@@ -252,13 +252,13 @@ asan_get_thread_fake_stack_handle(void)
  *
  * Note that this function expects "start" to be > "end" on downward-growing stack architectures;
  *
- * \param[in]  thread_fake_stack_handle  The asan fake stack reference for the thread we're scanning
- * \param[in]  slot                      The value on the machine stack we want to inspect
- * \param[in]  machine_stack_start       The extents of the real machine stack on which slot lives
- * \param[in]  machine_stack_end         The extents of the real machine stack on which slot lives
- * \param[out] fake_stack_start_out      The extents of the fake stack which contains real VALUEs
- * \param[out] fake_stack_end_out        The extents of the fake stack which contains real VALUEs
- * \return                               Whether slot is a pointer to a fake stack for the given machine stack range
+ * @param[in]  thread_fake_stack_handle  The asan fake stack reference for the thread we're scanning
+ * @param[in]  slot                      The value on the machine stack we want to inspect
+ * @param[in]  machine_stack_start       The extents of the real machine stack on which slot lives
+ * @param[in]  machine_stack_end         The extents of the real machine stack on which slot lives
+ * @param[out] fake_stack_start_out      The extents of the fake stack which contains real VALUEs
+ * @param[out] fake_stack_end_out        The extents of the fake stack which contains real VALUEs
+ * @return                               Whether slot is a pointer to a fake stack for the given machine stack range
 */
 
 static inline bool

kernel.rb

@@ -58,10 +58,10 @@ def clone(freeze: nil)
   #     a.freeze    #=> ["a", "b", "c"]
   #     a.frozen?   #=> true
   #--
-  # Determines if the object is frozen. Equivalent to \c Object\#frozen? in Ruby.
-  # \param[in] obj  the object to be determines
-  # \retval Qtrue if frozen
-  # \retval Qfalse if not frozen
+  # Determines if the object is frozen. Equivalent to `Object#frozen?` in Ruby.
+  # @param[in] obj  the object to be determines
+  # @retval Qtrue if frozen
+  # @retval Qfalse if not frozen
   #++
   #
   def frozen?