include/ruby/memory_view.h: add doxygen

I'm just applying doc/memory_view.md as a doxygen comment. [ci skip]

include/ruby/memory_view.h

@@ -1,4 +1,4 @@
-#ifndef RUBY_MEMORY_VIEW_H
+#ifndef RUBY_MEMORY_VIEW_H                           /*-*-C++-*-vi:se ft=cpp:*/
 #define RUBY_MEMORY_VIEW_H 1
 /**
  * @file
@@ -10,11 +10,25 @@
  * @brief      Memory View.
  */
 
-#include "ruby/internal/dllexport.h"
-#include "ruby/internal/stdbool.h"
-#include "ruby/internal/value.h"
-#include "ruby/intern.h"
+#include "ruby/internal/config.h"
 
+#ifdef STDC_HEADERS
+# include <stddef.h>                       /* size_t */
+#endif
+
+#if HAVE_SYS_TYPES_H
+# include <sys/types.h>                    /* ssize_t */
+#endif
+
+#include "ruby/internal/attr/pure.h"       /* RBIMPL_ATTR_PURE */
+#include "ruby/internal/core/rtypeddata.h" /* rb_data_type_t */
+#include "ruby/internal/dllexport.h"       /* RUBY_EXTERN */
+#include "ruby/internal/stdbool.h"         /* bool */
+#include "ruby/internal/value.h"           /* VALUE */
+
+/**
+ * Flags passed to rb_memory_view_get(), then to ::rb_memory_view_get_func_t.
+ */
 enum ruby_memory_view_flags {
     RUBY_MEMORY_VIEW_SIMPLE            = 0,
     RUBY_MEMORY_VIEW_WRITABLE          = (1<<0),
@@ -27,29 +41,56 @@ enum ruby_memory_view_flags {
     RUBY_MEMORY_VIEW_INDIRECT          = (1<<6) | RUBY_MEMORY_VIEW_STRIDES,
 };
 
+/** Memory view component metadata. */
 typedef struct {
+    /** @see ::rb_memory_view_t::format */
     char format;
+
+    /** :FIXME: what is a "native" size is unclear. */
     unsigned native_size_p: 1;
+
+    /** Endian of the component */
     unsigned little_endian_p: 1;
+
+    /** The component's offset. */
     size_t offset;
+
+    /** The component's size. */
     size_t size;
+
+    /**
+     * How many numbers of components are there. For instance "CCC"'s repeat is
+     * 3.
+     */
     size_t repeat;
 } rb_memory_view_item_component_t;
 
+/**
+ * A MemoryView  structure, `rb_memory_view_t`, is used  for exporting objects'
+ * MemoryView.
+ *
+ * This structure contains  the reference of the object, which  is the owner of
+ * the MemoryView, the pointer to the head of exported memory, and the metadata
+ * that  describes the  structure of  the  memory.  The  metadata can  describe
+ * multidimensional arrays with strides.
+ */
 typedef struct {
-    /* The original object that has the memory exported via this memory view.  */
+    /**
+     * The original object that has the memory exported via this memory view.
+     */
     VALUE obj;
 
-    /* The pointer to the exported memory. */
+    /** The pointer to the exported memory. */
     void *data;
 
-    /* The number of bytes in data. */
+    /** The number of bytes in data. */
     ssize_t byte_size;
 
-    /* true for readonly memory, false for writable memory. */
+    /** true for readonly memory, false for writable memory. */
     bool readonly;
 
-    /* A string to describe the format of an element, or NULL for unsigned bytes.
+    /**
+     * A string to describe the format of an element, or NULL for unsigned bytes.
      * The format string is a sequence of the following pack-template specifiers:
      *
      *   c, C, s, s!, S, S!, n, v, i, i!, I, I!, l, l!, L, L!,
@@ -69,83 +110,200 @@ typedef struct {
      */
     const char *format;
 
-    /* The number of bytes in each element.
+    /**
+     * The number of bytes in each element.
      * item_size should equal to rb_memory_view_item_size_from_format(format). */
     ssize_t item_size;
 
+    /** Description of each components. */
     struct {
-        /* The array of rb_memory_view_item_component_t that describes the
+        /**
+         * The array of rb_memory_view_item_component_t that describes the
          * item structure.  rb_memory_view_prepare_item_desc and
          * rb_memory_view_get_item allocate this memory if needed,
          * and rb_memory_view_release frees it. */
         const rb_memory_view_item_component_t *components;
 
-        /* The number of components in an item. */
+        /** The number of components in an item. */
         size_t length;
     } item_desc;
 
-    /* The number of dimension. */
+    /** The number of dimension. */
     ssize_t ndim;
 
-    /* ndim size array indicating the number of elements in each dimension.
+    /**
+     * ndim size array indicating the number of elements in each dimension.
      * This can be NULL when ndim == 1. */
     const ssize_t *shape;
 
-    /* ndim size array indicating the number of bytes to skip to go to the
+    /**
+     * ndim size array indicating the number of bytes to skip to go to the
      * next element in each dimension. */
     const ssize_t *strides;
 
-    /* The offset in each dimension when this memory view exposes a nested array.
+    /**
+     * The offset in each dimension when this memory view exposes a nested array.
      * Or, NULL when this memory view exposes a flat array. */
     const ssize_t *sub_offsets;
 
-    /* the private data for managing this exported memory */
+    /** the private data for managing this exported memory */
     void *private_data;
 } rb_memory_view_t;
 
+/** Type of function of ::rb_memory_view_entry_t::get_func. */
 typedef bool (* rb_memory_view_get_func_t)(VALUE obj, rb_memory_view_t *view, int flags);
+
+/** Type of function of ::rb_memory_view_entry_t::release_func. */
 typedef bool (* rb_memory_view_release_func_t)(VALUE obj, rb_memory_view_t *view);
+
+/** Type of function of ::rb_memory_view_entry_t::available_p_func. */
 typedef bool (* rb_memory_view_available_p_func_t)(VALUE obj);
 
+/** Operations applied to a specific kind of a memory view. */
 typedef struct {
+
+    /** Exports a memory view from a Ruby object. */
     rb_memory_view_get_func_t get_func;
+
+    /**
+     * Releases   a   memory  view   that   was   previously  generated   using
+     * ::rb_memory_view_entry_t::get_func.
+     */
     rb_memory_view_release_func_t release_func;
+
+    /**
+     * Queries if an object understands memory view protocol.
+     */
     rb_memory_view_available_p_func_t available_p_func;
 } rb_memory_view_entry_t;
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
 /* memory_view.c */
+
+/**
+ * Associates the passed class with the  passed memory view entry.  This has to
+ * be called before actually creating a memory view from an instance.
+ */
 bool rb_memory_view_register(VALUE klass, const rb_memory_view_entry_t *entry);
 
 RBIMPL_ATTR_PURE()
+/**
+ * Return `true` if the data in the MemoryView `view` is row-major contiguous.
+ *
+ * Return `false` otherwise.
+ */
 bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view);
+
 RBIMPL_ATTR_PURE()
+/**
+ * Return  `true`  if  the  data  in  the  MemoryView  `view`  is  column-major
+ * contiguous.
+ *
+ * Return `false` otherwise.
+ */
 bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view);
+
 RBIMPL_ATTR_NOALIAS()
+/**
+ * Fill the  `strides` array  with byte-Strides  of a  contiguous array  of the
+ * given shape with the given element size.
+ */
 void rb_memory_view_fill_contiguous_strides(const ssize_t ndim, const ssize_t item_size, const ssize_t *const shape, const bool row_major_p, ssize_t *const strides);
+
 RBIMPL_ATTR_NOALIAS()
+/**
+ * Fill the members of `view` as an 1-dimensional byte array.
+ */
 bool rb_memory_view_init_as_byte_array(rb_memory_view_t *view, VALUE obj, void *data, const ssize_t len, const bool readonly);
+
+/**
+ * Deconstructs    the     passed    format    string,    as     describe    in
+ * ::rb_memory_view_t::format.
+ */
 ssize_t rb_memory_view_parse_item_format(const char *format,
                                          rb_memory_view_item_component_t **members,
                                          size_t *n_members, const char **err);
+
+/**
+ * Calculate the number of bytes occupied by an element.
+ *
+ * When the calculation  fails, the failed location in `format`  is stored into
+ * `err`, and returns `-1`.
+ */
 ssize_t rb_memory_view_item_size_from_format(const char *format, const char **err);
+
+/**
+ * Calculate the location of the item indicated by the given `indices`.
+ *
+ * The length of `indices` must equal to `view->ndim`.
+ *
+ * This function initializes `view->item_desc` if needed.
+ */
 void *rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices);
+
+/**
+ * Return a value that consists of item members.
+ *
+ * When an item is a single member, the return value is a single value.
+ *
+ * When an item consists of multiple members, an array will be returned.
+ */
 VALUE rb_memory_view_extract_item_members(const void *ptr, const rb_memory_view_item_component_t *members, const size_t n_members);
+
+/** Fill the `item_desc` member of `view`. */
 void rb_memory_view_prepare_item_desc(rb_memory_view_t *view);
+
+/** * Return a value that consists of item members in the given memory view. */
 VALUE rb_memory_view_get_item(rb_memory_view_t *view, const ssize_t *indices);
 
+/**
+ * Return  `true` if  `obj` supports  to export  a MemoryView.   Return `false`
+ * otherwise.
+ *
+ * If   this  function   returns   `true`,  it   doesn't   mean  the   function
+ * `rb_memory_view_get` will succeed.
+ */
 bool rb_memory_view_available_p(VALUE obj);
+
+/**
+ * If the given  `obj` supports to export a MemoryView  that conforms the given
+ * `flags`, this function fills `view` by the information of the MemoryView and
+ * returns `true`.  In this case, the reference count of `obj` is increased.
+ *
+ * If the  given combination of `obj`  and `flags` cannot export  a MemoryView,
+ * this function returns `false`. The content  of `view` is not touched in this
+ * case.
+ *
+ * The exported  MemoryView must  be released by  `rb_memory_view_release` when
+ * the MemoryView is no longer needed.
+ */
 bool rb_memory_view_get(VALUE obj, rb_memory_view_t* memory_view, int flags);
+
+/**
+ * Release the  given MemoryView  `view` and decrement  the reference  count of
+ * `memory_view->obj`.
+ *
+ * Consumers must call  this function when the MemoryView is  no longer needed.
+ * Missing to call this function leads memory leak.
+ */
 bool rb_memory_view_release(rb_memory_view_t* memory_view);
 
 /* for testing */
+/** @cond INTERNAL_MACRO */
 RUBY_EXTERN VALUE rb_memory_view_exported_object_registry;
 RUBY_EXTERN const rb_data_type_t rb_memory_view_exported_object_registry_data_type;
+/** @endcond */
 
 RBIMPL_SYMBOL_EXPORT_END()
 
 RBIMPL_ATTR_PURE()
+/**
+ * Return  `true`  if  the  data  in the  MemoryView  `view`  is  row-major  or
+ * column-major contiguous.
+ *
+ * Return `false` otherwise.
+ */
 static inline bool
 rb_memory_view_is_contiguous(const rb_memory_view_t *view)
 {