diff --git a/include/prism.h b/include/prism.h index 755c38fca2..1304eddb52 100644 --- a/include/prism.h +++ b/include/prism.h @@ -53,6 +53,7 @@ PRISM_EXPORTED_FUNCTION const char * pm_version(void); * @param source The source to parse. * @param size The size of the source. * @param options The optional options to use when parsing. + * \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); @@ -62,6 +63,7 @@ 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); @@ -69,6 +71,7 @@ PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback(pm_par * Free any memory associated with the given parser. * * @param parser The parser to free. + * \public \memberof pm_parser */ PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser); @@ -77,13 +80,15 @@ 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. + * \public \memberof pm_parser */ typedef char * (pm_parse_stream_fgets_t)(char *string, int size, void *stream); @@ -96,6 +101,7 @@ typedef char * (pm_parse_stream_fgets_t)(char *string, int size, void *stream); * @param fgets The function to use to read from the stream. * @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 *fgets, const pm_options_t *options); @@ -112,6 +118,7 @@ PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse_stream(pm_parser_t *parser, pm_buff * @param stream The stream to parse. * @param fgets The function to use to read from the stream. * @param data The optional data to pass to the parser. + * \public \relatedalso pm_buffer_t */ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream(pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *fgets, const char *data); @@ -121,6 +128,7 @@ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream(pm_buffer_t *buffer, void * @param parser The parser to serialize. * @param list The list of comments to serialize. * @param buffer The buffer to serialize to. + * \public \memberof pm_buffer_t */ void pm_serialize_comment_list(pm_parser_t *parser, pm_list_t *list, pm_buffer_t *buffer); @@ -129,6 +137,7 @@ void pm_serialize_comment_list(pm_parser_t *parser, pm_list_t *list, pm_buffer_t * * @param encoding The encoding to serialize. * @param buffer The buffer to serialize to. + * \public \memberof pm_buffer_t */ void pm_serialize_encoding(const pm_encoding_t *encoding, pm_buffer_t *buffer); @@ -138,6 +147,7 @@ void pm_serialize_encoding(const pm_encoding_t *encoding, pm_buffer_t *buffer); * @param parser The parser to serialize. * @param node The node to serialize. * @param buffer The buffer to serialize to. + * \public \memberof pm_buffer_t */ void pm_serialize_content(pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer); @@ -147,6 +157,7 @@ void pm_serialize_content(pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buf * @param parser The parser to serialize. * @param node The node to serialize. * @param buffer The buffer to serialize to. + * \public \memberof pm_node */ PRISM_EXPORTED_FUNCTION void pm_serialize(pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer); @@ -157,6 +168,7 @@ PRISM_EXPORTED_FUNCTION void pm_serialize(pm_parser_t *parser, pm_node_t *node, * @param source The source to parse. * @param size The size of the source. * @param data The optional data to pass to the parser. + * \public \memberof pm_buffer_t */ PRISM_EXPORTED_FUNCTION void pm_serialize_parse(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data); @@ -167,6 +179,7 @@ PRISM_EXPORTED_FUNCTION void pm_serialize_parse(pm_buffer_t *buffer, const uint8 * @param source The source to parse. * @param size The size of the source. * @param data The optional data to pass to the parser. + * \public \relatedalso pm_buffer_t */ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_comments(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data); @@ -177,6 +190,7 @@ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_comments(pm_buffer_t *buffer, co * @param size The size of the source. * @param buffer The buffer to serialize to. * @param data The optional data to pass to the lexer. + * \public \relatedalso pm_buffer_t */ PRISM_EXPORTED_FUNCTION void pm_serialize_lex(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data); @@ -188,6 +202,7 @@ PRISM_EXPORTED_FUNCTION void pm_serialize_lex(pm_buffer_t *buffer, const uint8_t * @param source The source to parse. * @param size The size of the source. * @param data The optional data to pass to the parser. + * \public \relatedalso pm_buffer_t */ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_lex(pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data); @@ -200,6 +215,7 @@ PRISM_EXPORTED_FUNCTION void pm_serialize_parse_lex(pm_buffer_t *buffer, const u * @param size The size of the source. * @param data The optional data to pass to the parser. * @return True if the source parses without errors or warnings. + * \public \memberof pm_parser */ PRISM_EXPORTED_FUNCTION bool pm_parse_success_p(const uint8_t *source, size_t size, const char *data); @@ -229,6 +245,7 @@ const char * pm_token_type_human(pm_token_type_t token_type); * @param buffer The buffer to serialize to. * @param parser The parser that parsed the node. * @param node The node to serialize. + * \public \memberof pm_node */ PRISM_EXPORTED_FUNCTION void pm_dump_json(pm_buffer_t *buffer, const pm_parser_t *parser, const pm_node_t *node); diff --git a/include/prism/node.h b/include/prism/node.h index e8686a327c..24413d8b57 100644 --- a/include/prism/node.h +++ b/include/prism/node.h @@ -13,6 +13,7 @@ /** * Loop through each node in the node list, writing each node to the given * pm_node_t pointer. + * \public \related pm_node_list */ #define PM_NODE_LIST_FOREACH(list, index, node) \ for (size_t index = 0; index < (list)->size && ((node) = (list)->nodes[index]); index++) @@ -22,6 +23,7 @@ * * @param list The list to append to. * @param node The node to append. + * \private \memberof pm_node_list */ void pm_node_list_append(pm_node_list_t *list, pm_node_t *node); @@ -30,6 +32,7 @@ void pm_node_list_append(pm_node_list_t *list, pm_node_t *node); * * @param list The list to prepend to. * @param node The node to prepend. + * \private \memberof pm_node_list */ void pm_node_list_prepend(pm_node_list_t *list, pm_node_t *node); @@ -38,6 +41,7 @@ void pm_node_list_prepend(pm_node_list_t *list, pm_node_t *node); * * @param list The list to concatenate onto. * @param other The list to concatenate. + * \private \memberof pm_node_list */ void pm_node_list_concat(pm_node_list_t *list, pm_node_list_t *other); @@ -45,6 +49,7 @@ void pm_node_list_concat(pm_node_list_t *list, pm_node_list_t *other); * Free the internal memory associated with the given node list. * * @param list The list to free. + * \private \memberof pm_node_list */ void pm_node_list_free(pm_node_list_t *list); @@ -53,6 +58,7 @@ void pm_node_list_free(pm_node_list_t *list); * * @param parser The parser that owns the node. * @param node The node to deallocate. + * \public \memberof pm_parser */ PRISM_EXPORTED_FUNCTION void pm_node_destroy(pm_parser_t *parser, struct pm_node *node); @@ -61,6 +67,7 @@ PRISM_EXPORTED_FUNCTION void pm_node_destroy(pm_parser_t *parser, struct pm_node * * @param node_type The node type to convert to a string. * @return A string representation of the given node type. + * \public \memberof pm_node */ PRISM_EXPORTED_FUNCTION const char * pm_node_type_to_str(pm_node_type_t node_type); @@ -112,6 +119,7 @@ PRISM_EXPORTED_FUNCTION const char * pm_node_type_to_str(pm_node_type_t node_typ * @param node The root node to start visiting from. * @param visitor The callback to call for each node in the subtree. * @param data An opaque pointer that is passed to the visitor callback. + * \public \related pm_node */ PRISM_EXPORTED_FUNCTION void pm_visit_node(const pm_node_t *node, bool (*visitor)(const pm_node_t *node, void *data), void *data); @@ -123,6 +131,7 @@ PRISM_EXPORTED_FUNCTION void pm_visit_node(const pm_node_t *node, bool (*visitor * @param node The node to visit the children of. * @param visitor The callback to call for each child node. * @param data An opaque pointer that is passed to the visitor callback. + * \public \related pm_node */ PRISM_EXPORTED_FUNCTION void pm_visit_child_nodes(const pm_node_t *node, bool (*visitor)(const pm_node_t *node, void *data), void *data); diff --git a/include/prism/options.h b/include/prism/options.h index 3cb7304951..ca74ed0678 100644 --- a/include/prism/options.h +++ b/include/prism/options.h @@ -192,6 +192,7 @@ 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); @@ -200,6 +201,7 @@ 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); @@ -208,6 +210,7 @@ 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); @@ -216,6 +219,7 @@ 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); @@ -224,6 +228,7 @@ 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); @@ -232,6 +237,7 @@ 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); @@ -240,6 +246,7 @@ 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); @@ -252,6 +259,7 @@ 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); @@ -269,6 +277,7 @@ PRISM_EXPORTED_FUNCTION void pm_options_main_script_set(pm_options_t *options, b * @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); @@ -278,6 +287,7 @@ 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); @@ -288,6 +298,7 @@ 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); @@ -297,6 +308,7 @@ 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); @@ -304,6 +316,7 @@ PRISM_EXPORTED_FUNCTION const pm_string_t * pm_options_scope_local_get(const pm_ * 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); diff --git a/include/prism/prettyprint.h b/include/prism/prettyprint.h index 5a52b2b6b8..ede77259bd 100644 --- a/include/prism/prettyprint.h +++ b/include/prism/prettyprint.h @@ -26,6 +26,7 @@ void pm_prettyprint(void); * @param output_buffer The buffer to write the pretty-printed AST to. * @param parser The parser that parsed the AST. * @param node The root node of the AST to pretty-print. + * \public \memberof pm_node */ PRISM_EXPORTED_FUNCTION void pm_prettyprint(pm_buffer_t *output_buffer, const pm_parser_t *parser, const pm_node_t *node); diff --git a/include/prism/regexp.h b/include/prism/regexp.h index c0b3163e93..eb1e1958c3 100644 --- a/include/prism/regexp.h +++ b/include/prism/regexp.h @@ -17,12 +17,12 @@ #include /** - * 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); @@ -37,6 +37,7 @@ typedef void (*pm_regexp_error_callback_t)(const uint8_t *start, const uint8_t * * @param name_data The optional data to pass to the name callback. * @param error_callback The callback to call when a parse error is found. * @param error_data The data to pass to the error callback. + * \public \related pm_parser */ PRISM_EXPORTED_FUNCTION void pm_regexp_parse(pm_parser_t *parser, const uint8_t *source, size_t size, bool extended_mode, pm_regexp_name_callback_t name_callback, void *name_data, pm_regexp_error_callback_t error_callback, void *error_data); diff --git a/include/prism/util/pm_buffer.h b/include/prism/util/pm_buffer.h index 58f7b506cf..93918017ab 100644 --- a/include/prism/util/pm_buffer.h +++ b/include/prism/util/pm_buffer.h @@ -34,6 +34,7 @@ typedef struct { * Return the size of the pm_buffer_t struct. * * @returns The size of the pm_buffer_t struct. + * \public \static \memberof pm_buffer_t */ PRISM_EXPORTED_FUNCTION size_t pm_buffer_sizeof(void); @@ -51,6 +52,7 @@ 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,7 @@ 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 +70,7 @@ 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); @@ -212,6 +216,7 @@ 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); diff --git a/include/prism/util/pm_integer.h b/include/prism/util/pm_integer.h index a9e2966703..7b859bfae2 100644 --- a/include/prism/util/pm_integer.h +++ b/include/prism/util/pm_integer.h @@ -112,6 +112,7 @@ 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 +121,7 @@ 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); diff --git a/include/prism/util/pm_list.h b/include/prism/util/pm_list.h index 3512dee979..14a0456f3b 100644 --- a/include/prism/util/pm_list.h +++ b/include/prism/util/pm_list.h @@ -68,6 +68,7 @@ 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 +77,7 @@ 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 +93,7 @@ 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); diff --git a/include/prism/util/pm_string.h b/include/prism/util/pm_string.h index f99f1abdf3..0684efd2a0 100644 --- a/include/prism/util/pm_string.h +++ b/include/prism/util/pm_string.h @@ -60,12 +60,14 @@ typedef struct { * correct amount of memory in the FFI backend. * * @return The size of the pm_string_t struct. + * \public \static \memberof pm_string_t */ PRISM_EXPORTED_FUNCTION size_t pm_string_sizeof(void); /** * Defines an empty string. This is useful for initializing a string that will * be filled in later. + * \public \static \relates pm_string_t */ #define PM_STRING_EMPTY ((pm_string_t) { .type = PM_STRING_CONSTANT, .source = NULL, .length = 0 }) @@ -130,6 +132,7 @@ 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 +144,7 @@ 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,7 @@ 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,6 +182,7 @@ 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); @@ -184,6 +190,7 @@ PRISM_EXPORTED_FUNCTION const uint8_t * pm_string_source(const pm_string_t *stri * 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);