github
/
ruby
зеркало из https://github.com/github/ruby.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

[DOC] Unify Doxygen formats (#10285)

This commit is contained in:
Takashi Kokubun 2024-03-19 10:59:25 -07:00 коммит произвёл GitHub
Родитель 5c2937733c
Коммит cbcb2d46fc
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: B5690EEEBB952194
7 изменённых файлов: 136 добавлений и 136 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

104
class.c
Просмотреть файл

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

20
eval.c
Просмотреть файл

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

58
internal/sanitizers.h
Просмотреть файл

@ -95,7 +95,7 @@
# define VALGRIND_MAKE_MEM_UNDEFINED(p, n) 0 # define VALGRIND_MAKE_MEM_UNDEFINED(p, n) 0
#endif #endif
/*! /**
* This function asserts that a (continuous) memory region from ptr to size * This function asserts that a (continuous) memory region from ptr to size
* being "poisoned". Both read / write access to such memory region are * being "poisoned". Both read / write access to such memory region are
* prohibited until properly unpoisoned. The region must be previously * 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 * region to reuse later: poison when you keep it unused, and unpoison when you
* reuse. * reuse.
* *
* \param[in] ptr pointer to the beginning 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. * @param[in] size the length of the memory region to poison.
*/ */
static inline void static inline void
asan_poison_memory_region(const volatile void *ptr, size_t size) 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); __asan_poison_memory_region(ptr, size);
} }
/*! /**
* This is a variant of asan_poison_memory_region that takes a VALUE. * 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 static inline void
asan_poison_object(VALUE obj) 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)) #define asan_poison_object_if(ptr, obj) ((void)(ptr), (void)(obj))
#endif #endif
/*! /**
* This function predicates if the given object is fully addressable or not. * This function predicates if the given object is fully addressable or not.
* *
* \param[in] obj target object. * @param[in] obj target object.
* \retval 0 the given object is fully addressable. * @retval 0 the given object is fully addressable.
* \retval otherwise pointer to first such byte who is poisoned. * @retval otherwise pointer to first such byte who is poisoned.
*/ */
static inline void * static inline void *
asan_poisoned_object_p(VALUE obj) asan_poisoned_object_p(VALUE obj)
@ -149,7 +149,7 @@ asan_poisoned_object_p(VALUE obj)
return __asan_region_is_poisoned(ptr, SIZEOF_VALUE); return __asan_region_is_poisoned(ptr, SIZEOF_VALUE);
} }
/*! /**
* This function asserts that a (formally poisoned) memory region from ptr to * This function asserts that a (formally poisoned) memory region from ptr to
* size is now addressable. Write access to such memory region gets allowed. * size is now addressable. Write access to such memory region gets allowed.
* However read access might or might not be possible depending on situations, * 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 * the other hand, that memory region is fully defined and can be read
* immediately. * immediately.
* *
* \param[in] ptr pointer to the beginning of the memory region to unpoison. * @param[in] ptr pointer to the beginning of the memory region to unpoison.
* \param[in] size the length of the memory region. * @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] malloc_p if the memory region is like a malloc's return value or not.
*/ */
static inline void static inline void
asan_unpoison_memory_region(const volatile void *ptr, size_t size, bool malloc_p) 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. * This is a variant of asan_unpoison_memory_region that takes a VALUE.
* *
* \param[in] obj target object. * @param[in] obj target object.
* \param[in] malloc_p if the memory region is like a malloc's return value or not. * @param[in] malloc_p if the memory region is like a malloc's return value or not.
*/ */
static inline void static inline void
asan_unpoison_object(VALUE obj, bool newobj_p) 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 * 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 this variable has on the real frame; if not, it returns the origin
* address unmodified. * 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 * n.b. - this only works for addresses passed in from local variables on the same
* thread, because the ASAN fake stacks are threadlocal. * thread, because the ASAN fake stacks are threadlocal.
* *
* \param[in] slot the address of some local variable * @param[in] slot the address of some local variable
* \retval a pointer to something from that frame on the _real_ machine stack * @retval a pointer to something from that frame on the _real_ machine stack
*/ */
static inline void * static inline void *
asan_get_real_stack_addr(void* slot) asan_get_real_stack_addr(void* slot)
@ -230,10 +230,10 @@ asan_get_real_stack_addr(void* slot)
return addr ? addr : slot; return addr ? addr : slot;
} }
/*! /**
* Gets the current thread's fake stack handle, which can be passed into get_fake_stack_extents * 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 * static inline void *
asan_get_thread_fake_stack_handle(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(); return __asan_get_current_fake_stack();
} }
/*! /**
* Checks if the given VALUE _actually_ represents a pointer to an ASAN 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 * 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; * 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] 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] 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_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[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_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 * @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 * @return Whether slot is a pointer to a fake stack for the given machine stack range
*/ */
static inline bool static inline bool

8
kernel.rb
Просмотреть файл

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

32
object.c
Просмотреть файл

@ -660,9 +660,9 @@ rb_obj_size(VALUE self, VALUE args, VALUE obj)
/** /**
* :nodoc: * :nodoc:
*-- *--
* Default implementation of \c #initialize_copy * Default implementation of `#initialize_copy`
* \param[in,out] obj the receiver being initialized * @param[in,out] obj the receiver being initialized
* \param[in] orig the object to be copied from. * @param[in] orig the object to be copied from.
*++ *++
*/ */
VALUE VALUE
@ -676,13 +676,13 @@ rb_obj_init_copy(VALUE obj, VALUE orig)
return obj; return obj;
} }
/*! /**
* :nodoc: * :nodoc:
*-- *--
* Default implementation of \c #initialize_dup * Default implementation of `#initialize_dup`
* *
* \param[in,out] obj the receiver being initialized * @param[in,out] obj the receiver being initialized
* \param[in] orig the object to be dup from. * @param[in] orig the object to be dup from.
*++ *++
**/ **/
VALUE VALUE
@ -692,14 +692,14 @@ rb_obj_init_dup_clone(VALUE obj, VALUE orig)
return obj; return obj;
} }
/*! /**
* :nodoc: * :nodoc:
*-- *--
* Default implementation of \c #initialize_clone * Default implementation of `#initialize_clone`
* *
* \param[in] The number of arguments * @param[in] The number of arguments
* \param[in] The array of arguments * @param[in] The array of arguments
* \param[in] obj the receiver being initialized * @param[in] obj the receiver being initialized
*++ *++
**/ **/
static VALUE static VALUE
@ -2213,12 +2213,12 @@ rb_class_new_instance(int argc, const VALUE *argv, VALUE klass)
* BasicObject.superclass #=> nil * 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. * It skips modules.
* \param[in] klass a Class object * @param[in] klass a Class object
* \return the superclass, or \c Qnil if \a klass does not have a parent class. * @return the superclass, or `Qnil` if `klass` does not have a parent class.
* \sa rb_class_get_superclass * @sa rb_class_get_superclass
*++ *++
*/ */

2
template/Doxyfile.tmpl
Просмотреть файл

@ -621,7 +621,7 @@ HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = YES HIDE_IN_BODY_DOCS = YES
# The INTERNAL_DOCS tag determines if documentation that is typed after a # 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. # will be excluded. Set it to YES to include the internal documentation.
# The default value is: NO. # The default value is: NO.

48
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); return gccct_method_search_slowpath(vm, klass, mid, argc, index);
} }
/*! /**
* \internal * @internal
* calls the specified method. * calls the specified method.
* *
* This function is called by functions in rb_call* family. * This function is called by functions in rb_call* family.
* \param ec current execution context * @param ec current execution context
* \param recv receiver of the method * @param recv receiver of the method
* \param mid an ID that represents the name of the method * @param mid an ID that represents the name of the method
* \param argc the number of method arguments * @param argc the number of method arguments
* \param argv a pointer to an array of method arguments * @param argv a pointer to an array of method arguments
* \param scope * @param scope
* \param self self in the caller. Qundef means no self is considered and * @param self self in the caller. Qundef means no self is considered and
* protected methods cannot be called * 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 static inline VALUE
rb_call0(rb_execution_context_t *ec, 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. * calls the specified method.
* *
* This function is called by functions in rb_call* family. * This function is called by functions in rb_call* family.
* \param recv receiver * @param recv receiver
* \param mid an ID that represents the name of the method * @param mid an ID that represents the name of the method
* \param argc the number of method arguments * @param argc the number of method arguments
* \param argv a pointer to an array of method arguments * @param argv a pointer to an array of method arguments
* \param scope * @param scope
*/ */
static inline VALUE static inline VALUE
rb_call(VALUE recv, ID mid, int argc, const VALUE *argv, call_type scope) 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); return rb_funcallv(recv, mid, n, argv);
} }
/*! /**
* Calls a method only if it is the basic method of `ancestor` * Calls a method only if it is the basic method of `ancestor`
* otherwise returns Qundef; * otherwise returns Qundef;
* \param recv receiver of the method * @param recv receiver of the method
* \param mid an ID that represents the name of the method * @param mid an ID that represents the name of the method
* \param ancestor the Class that defined the basic method * @param ancestor the Class that defined the basic method
* \param argc the number of arguments * @param argc the number of arguments
* \param argv pointer to an array of method arguments * @param argv pointer to an array of method arguments
* \param kw_splat bool * @param kw_splat bool
*/ */
VALUE VALUE
rb_check_funcall_basic_kw(VALUE recv, ID mid, VALUE ancestor, int argc, const VALUE *argv, int kw_splat) rb_check_funcall_basic_kw(VALUE recv, ID mid, VALUE ancestor, int argc, const VALUE *argv, int kw_splat)