Merge pull request #3641 from ruby/memberof

Add `\memberof` annotations

Author: kddnewton

include/prism.h

@@ -56,6 +56,8 @@ PRISM_EXPORTED_FUNCTION const char * pm_version(void);
  * @param size The size of the source.
  * @param options The optional options to use when parsing. These options must
  *   live for the whole lifetime of this parser.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION void pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const pm_options_t *options);
 
@@ -65,6 +67,8 @@ PRISM_EXPORTED_FUNCTION void pm_parser_init(pm_parser_t *parser, const uint8_t *
  *
  * @param parser The parser to register the callback with.
  * @param callback The callback to register.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback(pm_parser_t *parser, pm_encoding_changed_callback_t callback);
 
@@ -75,6 +79,8 @@ PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback(pm_par
  * parser.
  *
  * @param parser The parser to free.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser);
 
@@ -83,11 +89,13 @@ PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser);
  *
  * @param parser The parser to use.
  * @return The AST representing the source.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse(pm_parser_t *parser);
 
 /**
- * This function is used in pm_parse_stream to retrieve a line of input from a
+ * This function is used in pm_parse_stream() to retrieve a line of input from a
  * stream. It closely mirrors that of fgets so that fgets can be used as the
  * default implementation.
  */
@@ -110,6 +118,8 @@ typedef int (pm_parse_stream_feof_t)(void *stream);
  * @param stream_feof The function to use to determine if the stream has hit eof.
  * @param options The optional options to use when parsing.
  * @return The AST representing the source.
+ *
+ * \public \memberof pm_parser
  */
 PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse_stream(pm_parser_t *parser, pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *stream_fgets, pm_parse_stream_feof_t *stream_feof, const pm_options_t *options);
 

include/prism/options.h

@@ -237,6 +237,8 @@ static const uint8_t PM_OPTIONS_COMMAND_LINE_X = 0x20;
  * @param shebang_callback The shebang callback to set.
  * @param shebang_callback_data Any additional data that should be passed along
  *   to the callback.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_shebang_callback_set(pm_options_t *options, pm_options_shebang_callback_t shebang_callback, void *shebang_callback_data);
 
@@ -245,6 +247,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_shebang_callback_set(pm_options_t *optio
  *
  * @param options The options struct to set the filepath on.
  * @param filepath The filepath to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_filepath_set(pm_options_t *options, const char *filepath);
 
@@ -253,6 +257,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_filepath_set(pm_options_t *options, cons
  *
  * @param options The options struct to set the line on.
  * @param line The line to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_line_set(pm_options_t *options, int32_t line);
 
@@ -261,6 +267,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_line_set(pm_options_t *options, int32_t
  *
  * @param options The options struct to set the encoding on.
  * @param encoding The encoding to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_encoding_set(pm_options_t *options, const char *encoding);
 
@@ -269,6 +277,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_encoding_set(pm_options_t *options, cons
  *
  * @param options The options struct to set the encoding_locked value on.
  * @param encoding_locked The encoding_locked value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_encoding_locked_set(pm_options_t *options, bool encoding_locked);
 
@@ -277,6 +287,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_encoding_locked_set(pm_options_t *option
  *
  * @param options The options struct to set the frozen string literal value on.
  * @param frozen_string_literal The frozen string literal value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_frozen_string_literal_set(pm_options_t *options, bool frozen_string_literal);
 
@@ -285,6 +297,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_frozen_string_literal_set(pm_options_t *
  *
  * @param options The options struct to set the command line option on.
  * @param command_line The command_line value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_command_line_set(pm_options_t *options, uint8_t command_line);
 
@@ -297,6 +311,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_command_line_set(pm_options_t *options,
  * @param version The version to set.
  * @param length The length of the version string.
  * @return Whether or not the version was parsed successfully.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION bool pm_options_version_set(pm_options_t *options, const char *version, size_t length);
 
@@ -305,6 +321,8 @@ PRISM_EXPORTED_FUNCTION bool pm_options_version_set(pm_options_t *options, const
  *
  * @param options The options struct to set the main script value on.
  * @param main_script The main script value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_main_script_set(pm_options_t *options, bool main_script);
 
@@ -313,6 +331,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_main_script_set(pm_options_t *options, b
  *
  * @param options The options struct to set the partial script value on.
  * @param partial_script The partial script value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_partial_script_set(pm_options_t *options, bool partial_script);
 
@@ -321,6 +341,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_partial_script_set(pm_options_t *options
  *
  * @param options The options struct to set the freeze value on.
  * @param freeze The freeze value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_freeze_set(pm_options_t *options, bool freeze);
 
@@ -330,6 +352,8 @@ PRISM_EXPORTED_FUNCTION void pm_options_freeze_set(pm_options_t *options, bool f
  * @param options The options struct to initialize the scopes array on.
  * @param scopes_count The number of scopes to allocate.
  * @return Whether or not the scopes array was initialized successfully.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION bool pm_options_scopes_init(pm_options_t *options, size_t scopes_count);
 
@@ -339,6 +363,8 @@ PRISM_EXPORTED_FUNCTION bool pm_options_scopes_init(pm_options_t *options, size_
  * @param options The options struct to get the scope from.
  * @param index The index of the scope to get.
  * @return A pointer to the scope at the given index.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION const pm_options_scope_t * pm_options_scope_get(const pm_options_t *options, size_t index);
 
@@ -349,6 +375,8 @@ PRISM_EXPORTED_FUNCTION const pm_options_scope_t * pm_options_scope_get(const pm
  * @param scope The scope struct to initialize.
  * @param locals_count The number of locals to allocate.
  * @return Whether or not the scope was initialized successfully.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION bool pm_options_scope_init(pm_options_scope_t *scope, size_t locals_count);
 
@@ -358,6 +386,8 @@ PRISM_EXPORTED_FUNCTION bool pm_options_scope_init(pm_options_scope_t *scope, si
  * @param scope The scope struct to get the local from.
  * @param index The index of the local to get.
  * @return A pointer to the local at the given index.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION const pm_string_t * pm_options_scope_local_get(const pm_options_scope_t *scope, size_t index);
 
@@ -366,13 +396,17 @@ PRISM_EXPORTED_FUNCTION const pm_string_t * pm_options_scope_local_get(const pm_
  *
  * @param scope The scope struct to set the forwarding on.
  * @param forwarding The forwarding value to set.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_scope_forwarding_set(pm_options_scope_t *scope, uint8_t forwarding);
 
 /**
  * Free the internal memory associated with the options.
  *
  * @param options The options struct whose internal memory should be freed.
+ *
+ * \public \memberof pm_options
  */
 PRISM_EXPORTED_FUNCTION void pm_options_free(pm_options_t *options);
 

include/prism/regexp.h

@@ -17,12 +17,12 @@
 #include <string.h>
 
 /**
- * This callback is called when a named capture group is found.
+ * This callback is called by pm_regexp_parse() when a named capture group is found.
  */
 typedef void (*pm_regexp_name_callback_t)(const pm_string_t *name, void *data);
 
 /**
- * This callback is called when a parse error is found.
+ * This callback is called by pm_regexp_parse() when a parse error is found.
  */
 typedef void (*pm_regexp_error_callback_t)(const uint8_t *start, const uint8_t *end, const char *message, void *data);
 

include/prism/util/pm_buffer.h

@@ -51,6 +51,8 @@ bool pm_buffer_init_capacity(pm_buffer_t *buffer, size_t capacity);
  *
  * @param buffer The buffer to initialize.
  * @returns True if the buffer was initialized successfully, false otherwise.
+ *
+ * \public \memberof pm_buffer_t
  */
 PRISM_EXPORTED_FUNCTION bool pm_buffer_init(pm_buffer_t *buffer);
 
@@ -59,6 +61,8 @@ PRISM_EXPORTED_FUNCTION bool pm_buffer_init(pm_buffer_t *buffer);
  *
  * @param buffer The buffer to get the value of.
  * @returns The value of the buffer.
+ *
+ * \public \memberof pm_buffer_t
  */
 PRISM_EXPORTED_FUNCTION char * pm_buffer_value(const pm_buffer_t *buffer);
 
@@ -67,6 +71,8 @@ PRISM_EXPORTED_FUNCTION char * pm_buffer_value(const pm_buffer_t *buffer);
  *
  * @param buffer The buffer to get the length of.
  * @returns The length of the buffer.
+ *
+ * \public \memberof pm_buffer_t
  */
 PRISM_EXPORTED_FUNCTION size_t pm_buffer_length(const pm_buffer_t *buffer);
 
@@ -222,6 +228,8 @@ void pm_buffer_insert(pm_buffer_t *buffer, size_t index, const char *value, size
  * Free the memory associated with the buffer.
  *
  * @param buffer The buffer to free.
+ *
+ * \public \memberof pm_buffer_t
  */
 PRISM_EXPORTED_FUNCTION void pm_buffer_free(pm_buffer_t *buffer);
 

include/prism/util/pm_integer.h

@@ -112,6 +112,8 @@ void pm_integers_reduce(pm_integer_t *numerator, pm_integer_t *denominator);
  *
  * @param buffer The buffer to append the string to.
  * @param integer The integer to convert to a string.
+ *
+ * \public \memberof pm_integer_t
  */
 PRISM_EXPORTED_FUNCTION void pm_integer_string(pm_buffer_t *buffer, const pm_integer_t *integer);
 
@@ -120,6 +122,8 @@ PRISM_EXPORTED_FUNCTION void pm_integer_string(pm_buffer_t *buffer, const pm_int
  * the integer exceeds the size of a single node in the linked list.
  *
  * @param integer The integer to free.
+ *
+ * \public \memberof pm_integer_t
  */
 PRISM_EXPORTED_FUNCTION void pm_integer_free(pm_integer_t *integer);
 

include/prism/util/pm_list.h

@@ -68,6 +68,8 @@ typedef struct {
  *
  * @param list The list to check.
  * @return True if the given list is empty, otherwise false.
+ *
+ * \public \memberof pm_list_t
  */
 PRISM_EXPORTED_FUNCTION bool pm_list_empty_p(pm_list_t *list);
 
@@ -76,6 +78,8 @@ PRISM_EXPORTED_FUNCTION bool pm_list_empty_p(pm_list_t *list);
  *
  * @param list The list to check.
  * @return The size of the list.
+ *
+ * \public \memberof pm_list_t
  */
 PRISM_EXPORTED_FUNCTION size_t pm_list_size(pm_list_t *list);
 
@@ -91,6 +95,8 @@ void pm_list_append(pm_list_t *list, pm_list_node_t *node);
  * Deallocate the internal state of the given list.
  *
  * @param list The list to free.
+ *
+ * \public \memberof pm_list_t
  */
 PRISM_EXPORTED_FUNCTION void pm_list_free(pm_list_t *list);
 

include/prism/util/pm_string.h

@@ -130,6 +130,8 @@ typedef enum {
  * @param string The string to initialize.
  * @param filepath The filepath to read.
  * @return The success of the read, indicated by the value of the enum.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION pm_string_init_result_t pm_string_mapped_init(pm_string_t *string, const char *filepath);
 
@@ -141,6 +143,8 @@ PRISM_EXPORTED_FUNCTION pm_string_init_result_t pm_string_mapped_init(pm_string_
  * @param string The string to initialize.
  * @param filepath The filepath to read.
  * @return The success of the read, indicated by the value of the enum.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION pm_string_init_result_t pm_string_file_init(pm_string_t *string, const char *filepath);
 
@@ -169,6 +173,8 @@ int pm_string_compare(const pm_string_t *left, const pm_string_t *right);
  *
  * @param string The string to get the length of.
  * @return The length of the string.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION size_t pm_string_length(const pm_string_t *string);
 
@@ -177,13 +183,17 @@ PRISM_EXPORTED_FUNCTION size_t pm_string_length(const pm_string_t *string);
  *
  * @param string The string to get the start pointer of.
  * @return The start pointer of the string.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION const uint8_t * pm_string_source(const pm_string_t *string);
 
 /**
  * Free the associated memory of the given string.
  *
  * @param string The string to free.
+ *
+ * \public \memberof pm_string_t
  */
 PRISM_EXPORTED_FUNCTION void pm_string_free(pm_string_t *string);