From cbcb2d46fc6d0971084b41df987480d2d9355328 Mon Sep 17 00:00:00 2001 From: Takashi Kokubun Date: Tue, 19 Mar 2024 10:59:25 -0700 Subject: [PATCH] [DOC] Unify Doxygen formats (#10285) --- class.c | 106 ++++++++++++++++++++--------------------- eval.c | 20 ++++---- internal/sanitizers.h | 58 +++++++++++----------- kernel.rb | 8 ++-- object.c | 32 ++++++------- template/Doxyfile.tmpl | 2 +- vm_eval.c | 48 +++++++++---------- 7 files changed, 137 insertions(+), 137 deletions(-) diff --git a/class.c b/class.c index cee2065ae4320a..46b8c1f74a5a6b 100644 --- a/class.c +++ b/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) diff --git a/eval.c b/eval.c index c855a4952e4e02..a405857f9aebe1 100644 --- a/eval.c +++ b/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) diff --git a/internal/sanitizers.h b/internal/sanitizers.h index 345380cebe833c..b0eb1fc851b415 100644 --- a/internal/sanitizers.h +++ b/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,10 +230,10 @@ 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) @@ -241,7 +241,7 @@ 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 diff --git a/kernel.rb b/kernel.rb index 9b853e9560c03d..541d0cfd9d11bf 100644 --- a/kernel.rb +++ b/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? diff --git a/object.c b/object.c index 3b856c730ac0cb..8eee22fbb4a73c 100644 --- a/object.c +++ b/object.c @@ -660,9 +660,9 @@ rb_obj_size(VALUE self, VALUE args, VALUE obj) /** * :nodoc: *-- - * Default implementation of \c #initialize_copy - * \param[in,out] obj the receiver being initialized - * \param[in] orig the object to be copied from. + * Default implementation of `#initialize_copy` + * @param[in,out] obj the receiver being initialized + * @param[in] orig the object to be copied from. *++ */ VALUE @@ -676,13 +676,13 @@ rb_obj_init_copy(VALUE obj, VALUE orig) return obj; } -/*! +/** * :nodoc: *-- - * Default implementation of \c #initialize_dup + * Default implementation of `#initialize_dup` * - * \param[in,out] obj the receiver being initialized - * \param[in] orig the object to be dup from. + * @param[in,out] obj the receiver being initialized + * @param[in] orig the object to be dup from. *++ **/ VALUE @@ -692,14 +692,14 @@ rb_obj_init_dup_clone(VALUE obj, VALUE orig) return obj; } -/*! +/** * :nodoc: *-- - * Default implementation of \c #initialize_clone + * Default implementation of `#initialize_clone` * - * \param[in] The number of arguments - * \param[in] The array of arguments - * \param[in] obj the receiver being initialized + * @param[in] The number of arguments + * @param[in] The array of arguments + * @param[in] obj the receiver being initialized *++ **/ static VALUE @@ -2213,12 +2213,12 @@ rb_class_new_instance(int argc, const VALUE *argv, VALUE klass) * BasicObject.superclass #=> nil * *-- - * Returns the superclass of \a klass. Equivalent to \c Class\#superclass in Ruby. + * Returns the superclass of `klass`. Equivalent to `Class#superclass` in Ruby. * * It skips modules. - * \param[in] klass a Class object - * \return the superclass, or \c Qnil if \a klass does not have a parent class. - * \sa rb_class_get_superclass + * @param[in] klass a Class object + * @return the superclass, or `Qnil` if `klass` does not have a parent class. + * @sa rb_class_get_superclass *++ */ diff --git a/template/Doxyfile.tmpl b/template/Doxyfile.tmpl index c801e0e79bb4db..c04f14977de323 100644 --- a/template/Doxyfile.tmpl +++ b/template/Doxyfile.tmpl @@ -621,7 +621,7 @@ HIDE_FRIEND_COMPOUNDS = NO HIDE_IN_BODY_DOCS = YES # The INTERNAL_DOCS tag determines if documentation that is typed after a -# \internal command is included. If the tag is set to NO then the documentation +# @internal command is included. If the tag is set to NO then the documentation # will be excluded. Set it to YES to include the internal documentation. # The default value is: NO. diff --git a/vm_eval.c b/vm_eval.c index c9a9751ab3e5ac..50c81f79d25353 100644 --- a/vm_eval.c +++ b/vm_eval.c @@ -505,21 +505,21 @@ gccct_method_search(rb_execution_context_t *ec, VALUE recv, ID mid, int argc) return gccct_method_search_slowpath(vm, klass, mid, argc, index); } -/*! - * \internal +/** + * @internal * calls the specified method. * * This function is called by functions in rb_call* family. - * \param ec current execution context - * \param recv receiver of the method - * \param mid an ID that represents the name of the method - * \param argc the number of method arguments - * \param argv a pointer to an array of method arguments - * \param scope - * \param self self in the caller. Qundef means no self is considered and + * @param ec current execution context + * @param recv receiver of the method + * @param mid an ID that represents the name of the method + * @param argc the number of method arguments + * @param argv a pointer to an array of method arguments + * @param scope + * @param self self in the caller. Qundef means no self is considered and * protected methods cannot be called * - * \note \a self is used in order to controlling access to protected methods. + * @note `self` is used in order to controlling access to protected methods. */ static inline VALUE rb_call0(rb_execution_context_t *ec, @@ -881,16 +881,16 @@ rb_method_call_status(rb_execution_context_t *ec, const rb_callable_method_entry } -/*! - * \internal +/** + * @internal * calls the specified method. * * This function is called by functions in rb_call* family. - * \param recv receiver - * \param mid an ID that represents the name of the method - * \param argc the number of method arguments - * \param argv a pointer to an array of method arguments - * \param scope + * @param recv receiver + * @param mid an ID that represents the name of the method + * @param argc the number of method arguments + * @param argv a pointer to an array of method arguments + * @param scope */ static inline VALUE rb_call(VALUE recv, ID mid, int argc, const VALUE *argv, call_type scope) @@ -1141,15 +1141,15 @@ rb_funcall(VALUE recv, ID mid, int n, ...) return rb_funcallv(recv, mid, n, argv); } -/*! +/** * Calls a method only if it is the basic method of `ancestor` * otherwise returns Qundef; - * \param recv receiver of the method - * \param mid an ID that represents the name of the method - * \param ancestor the Class that defined the basic method - * \param argc the number of arguments - * \param argv pointer to an array of method arguments - * \param kw_splat bool + * @param recv receiver of the method + * @param mid an ID that represents the name of the method + * @param ancestor the Class that defined the basic method + * @param argc the number of arguments + * @param argv pointer to an array of method arguments + * @param kw_splat bool */ VALUE rb_check_funcall_basic_kw(VALUE recv, ID mid, VALUE ancestor, int argc, const VALUE *argv, int kw_splat)