Document lifetime of pm_options_t

include/prism.h

@@ -48,11 +48,13 @@ PRISM_EXPORTED_FUNCTION const char * pm_version(void);
 
 /**
  * Initialize a parser with the given start and end pointers.
+ * The resulting parser must eventually be freed with `pm_parser_free()`.
  *
  * @param parser The parser to initialize.
  * @param source The source to parse.
  * @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.
  */
 PRISM_EXPORTED_FUNCTION void pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const pm_options_t *options);
 
@@ -68,6 +70,9 @@ PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback(pm_par
 /**
  * Free any memory associated with the given parser.
  *
+ * Note: this does not free the `pm_options_t` object that was used to initialize the parser.
+ * See \ref pm_options_t::pm_options_free() "pm_options_free()".
+ *
  * @param parser The parser to free.
  */
 PRISM_EXPORTED_FUNCTION void pm_parser_free(pm_parser_t *parser);

include/prism/options.h

@@ -303,6 +303,10 @@ PRISM_EXPORTED_FUNCTION const pm_string_t * pm_options_scope_local_get(const pm_
 /**
  * Free the internal memory associated with the options.
  *
+ * Must be called after the parser was freed with \ref pm_parser::pm_parser_free() "pm_parser_free()".
+ * If multiple parsers are created with the same options object, they must all be freed first,
+ * before it is safe to free the options object.
+ *
  * @param options The options struct whose internal memory should be freed.
  */
 PRISM_EXPORTED_FUNCTION void pm_options_free(pm_options_t *options);