include/ruby/internal/intern/ruby.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]

1 files changed, 42 insertions, 2 deletions

diff --git a/include/ruby/internal/intern/ruby.h b/include/ruby/internal/intern/ruby.h
index 4df9d46de6..efe61424ca 100644
--- a/include/ruby/internal/intern/ruby.h
+++ b/include/ruby/internal/intern/ruby.h
@@ -20,17 +20,57 @@
  *             extension libraries.  They could be written in C++98.
  * @brief      Process-global APIs.
  */
+#include "ruby/internal/attr/nonnull.h"
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
 /* ruby.c */
+/** @alias{rb_get_argv} */
 #define rb_argv rb_get_argv()
+
+/**
+ * The value of `$0` at process bootup.
+ *
+ * @note  This is just a snapshot of `$0`, not the backend storage of it.  `$0`
+ *        could  become something  different because  it is  a writable  global
+ *        variable.  Modifying  it for instance affects  `ps(1)` output.  Don't
+ *        assume they are synced.
+ */
 RUBY_EXTERN VALUE rb_argv0;
+
+/* io.c */
+
+/**
+ * Queries the arguments passed to the current process that you can access from
+ * Ruby as `ARGV`.
+ *
+ * @return  An array of strings containing arguments passed to the process.
+ */
 VALUE rb_get_argv(void);
-void *rb_load_file(const char*);
-void *rb_load_file_str(VALUE);
+
+/* ruby.c */
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Loads the given  file.  This function opens the given  pathname for reading,
+ * parses the contents as a Ruby  script, and returns an opaque "node" pointer.
+ * You can then pass it to ruby_run_node() for evaluation.
+ *
+ * @param[in]  file  File name, or "-" to read from stdin.
+ * @return     Opaque "node" pointer.
+ */
+void *rb_load_file(const char *file);
+
+/**
+ * Identical to rb_load_file(), except it takes the argument as a Ruby's string
+ * instead of C's.
+ *
+ * @param[in]  file  File name, or "-" to read from stdin.
+ * @return     Opaque "node" pointer.
+ */
+void *rb_load_file_str(VALUE file);
 
 RBIMPL_SYMBOL_EXPORT_END()