ruby-changes:67763
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:01:41 +0900 (JST)
Subject: [ruby-changes:67763] 4f97917474 (master): include/ruby/internal/intern/parse.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=4f97917474 From 4f97917474ea67a711e89e6051047d4e657a9774 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: Mon, 8 Mar 2021 16:52:35 +0900 Subject: include/ruby/internal/intern/parse.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/internal/intern/parse.h | 153 ++++++++++++++++++++++++++++++++--- 1 file changed, 142 insertions(+), 11 deletions(-) diff --git a/include/ruby/internal/intern/parse.h b/include/ruby/internal/intern/parse.h index 25b3f63..7c4e992 100644 --- a/include/ruby/internal/intern/parse.h +++ b/include/ruby/internal/intern/parse.h @@ -21,41 +21,172 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/parse.h#L21 * @brief Public APIs related to ::rb_cSymbol. */ #include "ruby/internal/attr/const.h" +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" RBIMPL_SYMBOL_EXPORT_BEGIN() -/* parse.y */ -ID rb_id_attrset(ID); +/* symbol.c */ + +/** + * Calculates an ID of attribute writer. For instance it returns `:foo=` when + * passed `:foo`. + * + * @param[in] id An id. + * @exception rb_eNameError `id` is not for attributes (e.g. operator). + * @return Calculated name of attribute writer. + */ +ID rb_id_attrset(ID id); RBIMPL_ATTR_CONST() -int rb_is_const_id(ID); +/** + * Classifies the given ID, then sees if it is a constant. In case an ID is in + * Unicode (likely), its "constant"-ness is determined if its first character + * is either upper case or title case. Otherwise it is detected if case- + * folding the first character changes its case or not. + * + * @param[in] id An id to classify. + * @retval 1 It is a constant. + * @retval 0 It isn't. + */ +int rb_is_const_id(ID id); RBIMPL_ATTR_CONST() -int rb_is_global_id(ID); +/** + * Classifies the given ID, then sees if it is a global variable. A global + * variable must start with `$`. + * + * @param[in] id An id to classify. + * @retval 1 It is a global variable. + * @retval 0 It isn't. + */ +int rb_is_global_id(ID id); RBIMPL_ATTR_CONST() -int rb_is_instance_id(ID); +/** + * Classifies the given ID, then sees if it is an instance variable. An + * instance variable must start with `@`, but not `@@`. + * + * @param[in] id An id to classify. + * @retval 1 It is an instance variable. + * @retval 0 It isn't. + */ +int rb_is_instance_id(ID id); RBIMPL_ATTR_CONST() -int rb_is_attrset_id(ID); +/** + * Classifies the given ID, then sees if it is an attribute writer. An + * attribute writer is otherwise a local variable, except it ends with `=`. + * + * @param[in] id An id to classify. + * @retval 1 It is an attribute writer. + * @retval 0 It isn't. + */ +int rb_is_attrset_id(ID id); RBIMPL_ATTR_CONST() -int rb_is_class_id(ID); +/** + * Classifies the given ID, then sees if it is a class variable. A class + * variable is must start with `@@`. + * + * @param[in] id An id to classify. + * @retval 1 It is a class variable. + * @retval 0 It isn't. + */ +int rb_is_class_id(ID id); RBIMPL_ATTR_CONST() -int rb_is_local_id(ID); +/** + * Classifies the given ID, then sees if it is a local variable. A local + * variable starts with a lowercase character, followed by some alphanumeric + * characters or `_`, then ends with anything other than `!`, `?`, or `=`. + * + * @param[in] id An id to classify. + * @retval 1 It is a local variable. + * @retval 0 It isn't. + */ +int rb_is_local_id(ID id); RBIMPL_ATTR_CONST() +/** + * Classifies the given ID, then sees if it is a junk ID. An ID with no + * special syntactic structure is considered junk. This category includes for + * instance punctuation. + * + * @param[in] id An id to classify. + * @retval 1 It is a junk. + * @retval 0 It isn't. + */ int rb_is_junk_id(ID); -int rb_symname_p(const char*); + +RBIMPL_ATTR_NONNULL(()) +/** + * Sees if the passed C string constructs a valid syntactic symbol. Invalid + * ones for instance includes whitespaces. + * + * @param[in] str A C string to check. + * @retval 1 It is a valid symbol name. + * @retval 0 It is invalid as a symbol name. + */ +int rb_symname_p(const char *str); + +/* vm.c */ + +/** + * Queries the last match, or `Regexp.last_match`, or the `$~`. You don't have + * to use it, because in reality you can get `$~` using rb_gv_get() as usual. + * + * @retval RUBY_Qnil The method has not ran a regular expression. + * @retval otherwise An instance of ::rb_cMatch. + */ VALUE rb_backref_get(void); -void rb_backref_set(VALUE); + +/** + * Updates `$~`. You don't have to use it, because in reality you can set `$~` + * using rb_gv_set() as usual. + * + * @param[in] md Arbitrary Ruby object. + * @post The passed object is assigned to `$~`. + * + * @internal + * + * Yes, this function bypasses the Check_Type() that would normally prevent + * evil souls from assigning evil objects to `$~`. Use of this function is a + * really bad smell. + */ +void rb_backref_set(VALUE md); + +/** + * Queries the last line, or the `$_`. You don't have to use it, because in + * reality you can get `$_` using rb_gv_get() as usual. + * + * @retval RUBY_Qnil There has never been a "line" yet. + * @retval otherwise The last set `$_` value. + */ VALUE rb_lastline_get(void); -void rb_lastline_set(VALUE); + +/** + * Updates `$_`. You don't have to use it, because in reality you can set `$_` + * using rb_gv_set() as usual. + * + * @param[in] str Arbitrary Ruby object. + * @post The passed object is assigned to `$_`. + * + * @internal + * + * Unlike `$~`, you can assign non-strings to `$_`, even from ruby scripts. + */ +void rb_lastline_set(VALUE str); /* symbol.c */ + +/** + * Collects every single bits of symbols that have ever interned in the entire + * history of the current process. + * + * @return An array that contains all symbols that have ever existed. + */ VALUE rb_sym_all_symbols(void); RBIMPL_SYMBOL_EXPORT_END() -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/