From f31dc8a45877f6db810fa5177270789baefeee0e Mon Sep 17 00:00:00 2001 From: 卜部昌平 Date: Fri, 31 Jan 2020 13:10:55 +0900 Subject: a bit terse Doxygen comments [ci skip] Creative use of `@copydoc` Doxygen command and abusing its half-broken C parser let us delete some lines of documentations, while preserving document coverages. --- include/ruby/backward/cxxanyargs.hpp | 202 ++++++----------------------------- 1 file changed, 35 insertions(+), 167 deletions(-) (limited to 'include/ruby/backward') diff --git a/include/ruby/backward/cxxanyargs.hpp b/include/ruby/backward/cxxanyargs.hpp index 132956ec3d..7eaaa632a4 100644 --- a/include/ruby/backward/cxxanyargs.hpp +++ b/include/ruby/backward/cxxanyargs.hpp @@ -22,36 +22,27 @@ extern "C++" { /// problem because namespaces are allowed to reopen. namespace ruby { -/// @brief Backwards compatibility layer. +/// Backwards compatibility layer. namespace backward { -/// @brief Provides ANYARGS deprecation warnings. -/// -/// In C, ANYARGS means there is no function prototype. Literally anything, -/// even including nothing, can be a valid ANYARGS. So passing a correctly -/// prototyped function pointer to an ANYARGS-ed function parameter is valid, -/// at the same time passing an ANYARGS-ed function pointer to a granular typed -/// function parameter is also valid. However on the other hand in C++, -/// ANYARGS doesn't actually mean any number of arguments. C++'s ANYARGS means -/// _variadic_ number of arguments. This is incompatible with ordinal, correct -/// function prototypes. +/// Provides ANYARGS deprecation warnings. In C, ANYARGS means there is no +/// function prototype. Literally anything, even including nothing, can be a +/// valid ANYARGS. So passing a correctly prototyped function pointer to an +/// ANYARGS-ed function parameter is valid, at the same time passing an +/// ANYARGS-ed function pointer to a granular typed function parameter is also +/// valid. However on the other hand in C++, ANYARGS doesn't actually mean any +/// number of arguments. C++'s ANYARGS means _variadic_ number of arguments. +/// This is incompatible with ordinal, correct function prototypes. /// /// Luckily, function prototypes being distinct each other means they can be /// overloaded. We can provide a compatibility layer for older Ruby APIs which /// used to have ANYARGS. This namespace includes such attempts. namespace cxxanyargs { -/// @brief ANYARGS-ed function type. -typedef VALUE type(ANYARGS); - -/// @brief ANYARGS-ed function type, void variant. -typedef void void_type(ANYARGS); - -/// @brief ANYARGS-ed function type, int variant. -typedef int int_type(ANYARGS); - -/// @brief single-argumented function type. -typedef VALUE onearg_type(VALUE); +typedef VALUE type(ANYARGS); ///< ANYARGS-ed function type. +typedef void void_type(ANYARGS); ///< ANYARGS-ed function type, void variant. +typedef int int_type(ANYARGS); ///< ANYARGS-ed function type, int variant. +typedef VALUE onearg_type(VALUE); ///< Single-argumented function type. /// @name Hooking global variables /// @{ @@ -73,13 +64,6 @@ rb_define_virtual_variable(const char *q, type *w, void_type *e) } RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Getter function. -/// @param[in] e Setter function. -/// @note Both functions can be nullptr. -/// @see rb_define_hooked_variable() -/// @deprecated Use glanular typed overload instead. inline void rb_define_virtual_variable(const char *q, rb_gvar_getter_t *w, void_type *e) { @@ -88,13 +72,6 @@ rb_define_virtual_variable(const char *q, rb_gvar_getter_t *w, void_type *e) } RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Getter function. -/// @param[in] e Setter function. -/// @note Both functions can be nullptr. -/// @see rb_define_hooked_variable() -/// @deprecated Use glanular typed overload instead. inline void rb_define_virtual_variable(const char *q, type *w, rb_gvar_setter_t *e) { @@ -103,11 +80,6 @@ rb_define_virtual_variable(const char *q, type *w, rb_gvar_setter_t *e) } #ifdef HAVE_NULLPTR -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Getter function. -/// @param[in] e Setter function. -/// @see rb_define_hooked_variable() inline void rb_define_virtual_variable(const char *q, rb_gvar_getter_t *w, std::nullptr_t e) { @@ -115,12 +87,6 @@ rb_define_virtual_variable(const char *q, rb_gvar_getter_t *w, std::nullptr_t e) } RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Getter function. -/// @param[in] e Setter function. -/// @see rb_define_hooked_variable() -/// @deprecated Use glanular typed overload instead. inline void rb_define_virtual_variable(const char *q, type *w, std::nullptr_t e) { @@ -128,11 +94,6 @@ rb_define_virtual_variable(const char *q, type *w, std::nullptr_t e) ::rb_define_virtual_variable(q, r, e); } -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Getter function. -/// @param[in] e Setter function. -/// @see rb_define_hooked_variable() inline void rb_define_virtual_variable(const char *q, std::nullptr_t w, rb_gvar_setter_t *e) { @@ -140,12 +101,6 @@ rb_define_virtual_variable(const char *q, std::nullptr_t w, rb_gvar_setter_t *e) } RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Getter function. -/// @param[in] e Setter function. -/// @see rb_define_hooked_variable() -/// @deprecated Use glanular typed overload instead. inline void rb_define_virtual_variable(const char *q, std::nullptr_t w, void_type *e) { @@ -172,14 +127,6 @@ rb_define_hooked_variable(const char *q, VALUE *w, type *e, void_type *r) } RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Variable storage. -/// @param[in] e Getter function. -/// @param[in] r Setter function. -/// @note Both functions can be nullptr. -/// @see rb_define_virtual_variable() -/// @deprecated Use glanular typed overload instead. inline void rb_define_hooked_variable(const char *q, VALUE *w, rb_gvar_getter_t *e, void_type *r) { @@ -188,14 +135,6 @@ rb_define_hooked_variable(const char *q, VALUE *w, rb_gvar_getter_t *e, void_typ } RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Variable storage. -/// @param[in] e Getter function. -/// @param[in] r Setter function. -/// @note Both functions can be nullptr. -/// @see rb_define_virtual_variable() -/// @deprecated Use glanular typed overload instead. inline void rb_define_hooked_variable(const char *q, VALUE *w, type *e, rb_gvar_setter_t *r) { @@ -204,12 +143,6 @@ rb_define_hooked_variable(const char *q, VALUE *w, type *e, rb_gvar_setter_t *r) } #ifdef HAVE_NULLPTR -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Variable storage. -/// @param[in] e Getter function. -/// @param[in] r Setter function. -/// @see rb_define_virtual_variable() inline void rb_define_hooked_variable(const char *q, VALUE *w, rb_gvar_getter_t *e, std::nullptr_t r) { @@ -217,13 +150,6 @@ rb_define_hooked_variable(const char *q, VALUE *w, rb_gvar_getter_t *e, std::nul } RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Variable storage. -/// @param[in] e Getter function. -/// @param[in] r Setter function. -/// @see rb_define_virtual_variable() -/// @deprecated Use glanular typed overload instead. inline void rb_define_hooked_variable(const char *q, VALUE *w, type *e, std::nullptr_t r) { @@ -231,12 +157,6 @@ rb_define_hooked_variable(const char *q, VALUE *w, type *e, std::nullptr_t r) ::rb_define_hooked_variable(q, w, y, r); } -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Variable storage. -/// @param[in] e Getter function. -/// @param[in] r Setter function. -/// @see rb_define_virtual_variable() inline void rb_define_hooked_variable(const char *q, VALUE *w, std::nullptr_t e, rb_gvar_setter_t *r) { @@ -244,13 +164,6 @@ rb_define_hooked_variable(const char *q, VALUE *w, std::nullptr_t e, rb_gvar_set } RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Define a function-backended global variable. -/// @param[in] q Name of the variable. -/// @param[in] w Variable storage. -/// @param[in] e Getter function. -/// @param[in] r Setter function. -/// @see rb_define_virtual_variable() -/// @deprecated Use glanular typed overload instead. inline void rb_define_hooked_variable(const char *q, VALUE *w, std::nullptr_t e, void_type *r) { @@ -281,14 +194,6 @@ rb_iterate(onearg_type *q, VALUE w, type *e, VALUE r) } #ifdef HAVE_NULLPTR -/// @brief Old way to implement iterators. -/// @param[in] q A function that can yield. -/// @param[in] w Passed to `q`. -/// @param[in] e What is to be yielded. -/// @param[in] r Passed to `e`. -/// @return The return value of `q`. -/// @deprecated This function is obsolated since long before 2.x era. Do not -/// use it any longer. rb_block_call() is provided instead. inline VALUE rb_iterate(onearg_type *q, VALUE w, std::nullptr_t e, VALUE r) { @@ -315,14 +220,6 @@ rb_block_call(VALUE q, ID w, int e, const VALUE *r, type *t, VALUE y) } #ifdef HAVE_NULLPTR -/// @brief Call a method with a block. -/// @param[in] q The self. -/// @param[in] w The method. -/// @param[in] e The # of elems of `r` -/// @param[in] r The arguments. -/// @param[in] t What is to be yielded. -/// @param[in] y Passed to `t` -/// @return Return value of `q#w(*r,&t)` inline VALUE rb_block_call(VALUE q, ID w, int e, const VALUE *r, std::nullptr_t t, VALUE y) { @@ -422,15 +319,6 @@ rb_catch(const char *q, type *w, VALUE e) } #ifdef HAVE_NULLPTR -/// @brief An equivalent of `Kernel#catch`. -/// @param[in] q The "tag" string. -/// @param[in] w A function that can throw. -/// @param[in] e Passed to `w`. -/// @return What was thrown. -/// @see rb_block_call() -/// @see rb_protect() -/// @see rb_rb_catch_obj() -/// @see rb_rescue() inline VALUE rb_catch(const char *q, std::nullptr_t w, VALUE e) { @@ -600,17 +488,16 @@ rb_ivar_foreach(VALUE q, int_type *w, VALUE e) /// @} -/// @brief Driver for *_define_method -/// -/// ::rb_define_method function for instance takes a pointer to ANYARGS-ed -/// functions, which in fact varies 18 different prototypes. We still need to -/// preserve ANYARGS for storages but why not check the consistencies if -/// possible. In C++ a function has its own prototype, which is a compile-time -/// constant (static type) by nature. We can list up all the possible input -/// types and provide warnings for other cases. This is such attempt. +/// Driver for *_define_method. ::rb_define_method function for instance takes +/// a pointer to ANYARGS-ed functions, which in fact varies 18 different +/// prototypes. We still need to preserve ANYARGS for storages but why not +/// check the consistencies if possible. In C++ a function has its own +/// prototype, which is a compile-time constant (static type) by nature. We +/// can list up all the possible input types and provide warnings for other +/// cases. This is such attempt. namespace define_method { -/// @brief type of rb_f_notimplement +/// Type of ::rb_f_notimplement(). typedef VALUE notimpl_type(int, const VALUE *, VALUE, VALUE); /// @brief Template metaprogramming to generate function prototypes. @@ -637,10 +524,7 @@ struct driver { #if (RUBY_API_VERSION_MAJOR * 100 + RUBY_API_VERSION_MINOR) >= 301 RUBY_CXX_DEPRECATED("use of ANYARGS is deprecated") #endif - /// @brief Defines klass#mid as func, whose arity is N. - /// @param[in] klass Where the method lives. - /// @param[in] mid Name of the method to define. - /// @param[in] func Function that implements klass#mid. + /// @copydoc define(VALUE klass, T mid, U func) /// @deprecated Pass corrctly typed function instead. static inline void define(VALUE klass, T mid, type func) @@ -658,10 +542,7 @@ struct driver { F(klass, mid, reinterpret_cast(func), N); } - /// @brief Defines klass#mid as func, whose arity is N. - /// @param[in] klass Where the method lives. - /// @param[in] mid Name of the method to define. - /// @param[in] func Function that implements klass#mid. + /// @copydoc define(VALUE klass, T mid, U func) static inline void define(VALUE klass, T mid, notimpl_type func) { @@ -744,49 +625,36 @@ struct driver0 { /// @endcond }; -/// @brief Dispatches appropriate driver for ::rb_define_method -struct rb_define_method : public driver {}; - -/// @brief Dispatches appropriate driver for ::rb_define_method_id -struct rb_define_method_id : public driver {}; - -/// @brief Dispatches appropriate driver for ::rb_define_private_method -struct rb_define_private_method : public driver {}; - -/// @brief Dispatches appropriate driver for ::rb_define_protected_method -struct rb_define_protected_method : public driver {}; - -/// @brief Dispatches appropriate driver for ::rb_define_singleton_method -struct rb_define_singleton_method : public driver {}; - -/// @brief Dispatches appropriate driver for ::rb_define_module_function -struct rb_define_module_function : public driver {}; - -/// @brief Dispatches appropriate driver for ::rb_define_global_function -struct rb_define_global_function : public driver0 {}; +struct rb_define_method : public driver {}; ///< Dispatches appropriate driver for ::rb_define_method. +struct rb_define_method_id : public driver {}; ///< Dispatches appropriate driver for ::rb_define_method_id. +struct rb_define_private_method : public driver {}; ///< Dispatches appropriate driver for ::rb_define_private_method. +struct rb_define_protected_method : public driver {}; ///< Dispatches appropriate driver for ::rb_define_protected_method. +struct rb_define_singleton_method : public driver {}; ///< Dispatches appropriate driver for ::rb_define_singleton_method. +struct rb_define_module_function : public driver {}; ///< Dispatches appropriate driver for ::rb_define_module_function. +struct rb_define_global_function : public driver0 {}; ///< Dispatches appropriate driver for ::rb_define_global_function. /// @brief Defines klass\#mid. /// @param klass Where the method lives. -/// @copydetails #rb_define_global_function +/// @copydetails #rb_define_global_function(mid, func, arity) #define rb_define_method(klass, mid, func, arity) ruby::backward::cxxanyargs::define_method::rb_define_method::specific::define(klass, mid, func) -/// @copydoc #rb_define_method +/// @copydoc #rb_define_method(klass, mid, func, arity) #define rb_define_method_id(klass, mid, func, arity) ruby::backward::cxxanyargs::define_method::rb_define_method_id::specific::define(klass, mid, func) /// @brief Defines klass\#mid and makes it private. -/// @copydetails #rb_define_method +/// @copydetails #rb_define_method(klass, mid, func, arity) #define rb_define_private_method(klass, mid, func, arity) ruby::backward::cxxanyargs::define_method::rb_define_private_method::specific::define(klass, mid, func) /// @brief Defines klass\#mid and makes it protected. /// @copydetails #rb_define_method #define rb_define_protected_method(klass, mid, func, arity) ruby::backward::cxxanyargs::define_method::rb_define_protected_method::specific::define(klass, mid, func) -/// @brief Defines klass.mid. +/// @brief Defines klass.mid.(klass, mid, func, arity) /// @copydetails #rb_define_method #define rb_define_singleton_method(klass, mid, func, arity) ruby::backward::cxxanyargs::define_method::rb_define_singleton_method::specific::define(klass, mid, func) /// @brief Defines klass\#mid and makes it a module function. -/// @copydetails #rb_define_method +/// @copydetails #rb_define_method(klass, mid, func, arity) #define rb_define_module_function(klass, mid, func, arity) ruby::backward::cxxanyargs::define_method::rb_define_module_function::specific::define(klass, mid, func) /// @brief Defines ::rb_mKernel \#mid. -- cgit v1.2.3