Use Markdown in doc comments for better source readability.

git-svn-id: http://svn.drobilla.net/lad/trunk/lilv@5429 a436a847-0d15-0410-975c-d299462d15a1

1 files changed, 101 insertions, 101 deletions

diff --git a/lilv/lilv.h b/lilv/lilv.h
index df1a62c..5c26681 100644
--- a/lilv/lilv.h
+++ b/lilv/lilv.h
@@ -104,7 +104,7 @@ typedef void LilvNodes;          /**< set<Node>. */
    Convert a file URI string to a local path string.
    For example, "file://foo/bar/baz.ttl" returns "/foo/bar/baz.ttl".
    Return value is shared and must not be deleted by caller.
-   @return @a uri converted to a path, or NULL on failure (URI is not local).
+   @return `uri` converted to a path, or NULL on failure (URI is not local).
 */
 LILV_API const char*
 lilv_uri_to_path(const char* uri);
@@ -131,7 +131,7 @@ lilv_new_file_uri(LilvWorld* world, const char* host, const char* path);
 
 /**
    Create a new string value (with no language).
-   Returned value must be freed by caller with lilv_node_free()().
+   Returned value must be freed by caller with lilv_node_free().
 */
 LILV_API LilvNode*
 lilv_new_string(LilvWorld* world, const char* str);
@@ -200,8 +200,8 @@ lilv_node_is_uri(const LilvNode* value);
 
 /**
    Return this value as a URI string, e.g. "http://example.org/foo".
-   Valid to call only if lilv_node_is_uri(@a value) returns true.
-   Returned value is owned by @a value and must not be freed by caller.
+   Valid to call only if `lilv_node_is_uri(value)` returns true.
+   Returned value is owned by `value` and must not be freed by caller.
 */
 LILV_API const char*
 lilv_node_as_uri(const LilvNode* value);
@@ -214,28 +214,28 @@ lilv_node_is_blank(const LilvNode* value);
 
 /**
    Return this value as a blank node identifier, e.g. "genid03".
-   Valid to call only if lilv_node_is_blank(@a value) returns true.
-   Returned value is owned by @a value and must not be freed by caller.
+   Valid to call only if `lilv_node_is_blank(value)` returns true.
+   Returned value is owned by `value` and must not be freed by caller.
 */
 LILV_API const char*
 lilv_node_as_blank(const LilvNode* value);
 
 /**
    Return whether this value is a literal (i.e. not a URI).
-   Returns true if @a value is a string or numeric value.
+   Returns true if `value` is a string or numeric value.
 */
 LILV_API bool
 lilv_node_is_literal(const LilvNode* value);
 
 /**
    Return whether this value is a string literal.
-   Returns true if @a value is a string value (and not numeric).
+   Returns true if `value` is a string value (and not numeric).
 */
 LILV_API bool
 lilv_node_is_string(const LilvNode* value);
 
 /**
-   Return @a value as a string.
+   Return `value` as a string.
 */
 LILV_API const char*
 lilv_node_as_string(const LilvNode* value);
@@ -247,9 +247,9 @@ LILV_API bool
 lilv_node_is_float(const LilvNode* value);
 
 /**
-   Return @a value as a float.
-   Valid to call only if lilv_node_is_float(@a value) or
-   lilv_node_is_int(@a value) returns true.
+   Return `value` as a float.
+   Valid to call only if `lilv_node_is_float(value)` or
+   `lilv_node_is_int(value)` returns true.
 */
 LILV_API float
 lilv_node_as_float(const LilvNode* value);
@@ -261,8 +261,8 @@ LILV_API bool
 lilv_node_is_int(const LilvNode* value);
 
 /**
-   Return @a value as an integer.
-   Valid to call only if lilv_node_is_int(@a value) returns true.
+   Return `value` as an integer.
+   Valid to call only if `lilv_node_is_int(value)` returns true.
 */
 LILV_API int
 lilv_node_as_int(const LilvNode* value);
@@ -274,8 +274,8 @@ LILV_API bool
 lilv_node_is_bool(const LilvNode* value);
 
 /**
-   Return @a value as a bool.
-   Valid to call only if lilv_node_is_bool(@a value) returns true.
+   Return `value` as a bool.
+   Valid to call only if `lilv_node_is_bool(value)` returns true.
 */
 LILV_API bool
 lilv_node_as_bool(const LilvNode* value);
@@ -339,10 +339,10 @@ LILV_API bool
 lilv_plugin_classes_is_end(const LilvPluginClasses* collection, LilvIter* i);
 
 /**
-   Get a plugin class from @a classes by URI.
-   Return value is shared (stored in @a classes) and must not be freed or
+   Get a plugin class from `classes` by URI.
+   Return value is shared (stored in `classes`) and must not be freed or
    modified by the caller in any way.
-   @return NULL if no plugin class with @a uri is found in @a classes.
+   @return NULL if no plugin class with `uri` is found in `classes`.
 */
 LILV_API const LilvPluginClass*
 lilv_plugin_classes_get_by_uri(const LilvPluginClasses* classes,
@@ -389,10 +389,10 @@ LILV_API bool
 lilv_uis_is_end(const LilvUIs* collection, LilvIter* i);
 
 /**
-   Get a UI from @a uis by URI.
-   Return value is shared (stored in @a uis) and must not be freed or
+   Get a UI from `uis` by URI.
+   Return value is shared (stored in `uis`) and must not be freed or
    modified by the caller in any way.
-   @return NULL if no UI with @a uri is found in @a list.
+   @return NULL if no UI with `uri` is found in `list`.
 */
 LILV_API const LilvUI*
 lilv_uis_get_by_uri(const LilvUIs*  uis,
@@ -422,7 +422,7 @@ LILV_API LilvNode*
 lilv_nodes_get_first(const LilvNodes* collection);
 
 /**
-   Return whether @a values contains @a value.
+   Return whether `values` contains `value`.
 */
 LILV_API bool
 lilv_nodes_contains(const LilvNodes* values, const LilvNode* value);
@@ -451,10 +451,10 @@ LILV_API bool
 lilv_plugins_is_end(const LilvPlugins* collection, LilvIter* i);
 
 /**
-   Get a plugin from @a plugins by URI.
-   Return value is shared (stored in @a plugins) and must not be freed or
+   Get a plugin from `plugins` by URI.
+   Return value is shared (stored in `plugins`) and must not be freed or
    modified by the caller in any way.
-   @return NULL if no plugin with @a uri is found in @a plugins.
+   @return NULL if no plugin with `uri` is found in `plugins`.
 */
 LILV_API const LilvPlugin*
 lilv_plugins_get_by_uri(const LilvPlugins* plugins,
@@ -466,7 +466,7 @@ lilv_plugins_get_by_uri(const LilvPlugins* plugins,
    The "world" represents all Lilv state, and is used to discover/load/cache
    LV2 data (plugins, UIs, and extensions).
    Normal hosts which just need to load plugins by URI should simply use
-   @ref lilv_world_load_all to discover/load the system's LV2 resources.
+   lilv_world_load_all() to discover/load the system's LV2 resources.
    @{
 */
 
@@ -493,7 +493,7 @@ lilv_world_new(void);
 #define LILV_OPTION_DYN_MANIFEST "http://drobilla.net/ns/lilv#dyn-manifest"
 
 /**
-   Set an option option for @a world.
+   Set an option option for `world`.
 
    Currently recognized options:
    @ref LILV_OPTION_FILTER_LANG
@@ -507,7 +507,7 @@ lilv_world_set_option(LilvWorld*      world,
 /**
    Destroy the world, mwahaha.
    It is safe to call this function on NULL.
-   Note that destroying @a world will destroy all the objects it contains
+   Note that destroying `world` will destroy all the objects it contains
    (e.g. instances of LilvPlugin).  Do not destroy the world until you are
    finished with all objects that came from it.
 */
@@ -530,7 +530,7 @@ lilv_world_load_all(LilvWorld* world);
 
 /**
    Load a specific bundle.
-   @a bundle_uri must be a fully qualified URI to the bundle directory,
+   `bundle_uri` must be a fully qualified URI to the bundle directory,
    with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/
 
    Normal hosts should not need this function (use lilv_world_load_all).
@@ -556,12 +556,12 @@ LILV_API int
 lilv_world_unload_bundle(LilvWorld* world, LilvNode* bundle_uri);
 
 /**
-   Load all the data associated with the given @c resource.
+   Load all the data associated with the given `resource`.
    @param world The world.
    @param resource Must be a subject (i.e. a URI or a blank node).
    @return The number of files parsed, or -1 on error
 
-   All accessible data files linked to @c resource with rdfs:seeAlso will be
+   All accessible data files linked to `resource` with rdfs:seeAlso will be
    loaded into the world model.
 */
 LILV_API int
@@ -569,12 +569,12 @@ lilv_world_load_resource(LilvWorld*      world,
                          const LilvNode* resource);
 
 /**
-   Unload all the data associated with the given @c resource.
+   Unload all the data associated with the given `resource`.
    @param world The world.
    @param resource Must be a subject (i.e. a URI or a blank node).
 
    This unloads all data loaded by a previous call to
-   lilv_world_load_resource() with the given @c resource.
+   lilv_world_load_resource() with the given `resource`.
 */
 LILV_API int
 lilv_world_unload_resource(LilvWorld*      world,
@@ -601,7 +601,7 @@ lilv_world_get_plugin_classes(const LilvWorld* world);
    a query (at which time the data is cached with the LilvPlugin so future
    queries are very fast).
 
-   The returned list and the plugins it contains are owned by @a world
+   The returned list and the plugins it contains are owned by `world`
    and must not be freed by caller.
 */
 LILV_API const LilvPlugins*
@@ -609,7 +609,7 @@ lilv_world_get_all_plugins(const LilvWorld* world);
 
 /**
    Find nodes matching a triple pattern.
-   Either @c subject or @c object may be NULL (i.e. a wildcard), but not both.
+   Either `subject` or `object` may be NULL (i.e. a wildcard), but not both.
    @return All matches for the wildcard field, or NULL.
 */
 LILV_API LilvNodes*
@@ -656,20 +656,20 @@ lilv_world_ask(LilvWorld*      world,
 */
 
 /**
-   Check if @a plugin is valid.
+   Check if `plugin` is valid.
    This is not a rigorous validator, but can be used to reject some malformed
    plugins that could cause bugs (e.g. plugins with missing required fields).
 
    Note that normal hosts do NOT need to use this - lilv does not
    load invalid plugins into plugin lists.  This is included for plugin
    testing utilities, etc.
-   @return true iff @a plugin is valid.
+   @return true iff `plugin` is valid.
 */
 LILV_API bool
 lilv_plugin_verify(const LilvPlugin* plugin);
 
 /**
-   Get the URI of @a plugin.
+   Get the URI of `plugin`.
    Any serialization that refers to plugins should refer to them by this.
    Hosts SHOULD NOT save any filesystem paths, plugin indexes, etc. in saved
    files; save only the URI.
@@ -711,7 +711,7 @@ LILV_API const LilvNodes*
 lilv_plugin_get_data_uris(const LilvPlugin* plugin);
 
 /**
-   Get the (resolvable) URI of the shared library for @a plugin.
+   Get the (resolvable) URI of the shared library for `plugin`.
    Note this always returns a fully qualified URI.  If you want a local
    filesystem path, use lilv_uri_to_path.
    @return a shared string which must not be modified or freed.
@@ -720,7 +720,7 @@ LILV_API const LilvNode*
 lilv_plugin_get_library_uri(const LilvPlugin* plugin);
 
 /**
-   Get the name of @a plugin.
+   Get the name of `plugin`.
    This returns the name (doap:name) of the plugin.  The name may be
    translated according to the current locale, this value MUST NOT be used
    as a plugin identifier (use the URI for that).
@@ -737,7 +737,7 @@ lilv_plugin_get_class(const LilvPlugin* plugin);
 
 /**
    Get a value associated with the plugin in a plugin's data files.
-   @a predicate must be either a URI or a QName.
+   `predicate` must be either a URI or a QName.
 
    Returns the ?object of all triples found of the form:
 
@@ -821,7 +821,7 @@ lilv_plugin_get_num_ports(const LilvPlugin* p);
 
 /**
    Get the port ranges (minimum, maximum and default values) for all ports.
-   @a min_values, @a max_values and @a def_values must either point to an array
+   `min_values`, `max_values` and `def_values` must either point to an array
    of N floats, where N is the value returned by lilv_plugin_get_num_ports()
    for this plugin, or NULL.  The elements of the array will be set to the
    the minimum, maximum and default values of the ports on this plugin,
@@ -882,14 +882,14 @@ LILV_API uint32_t
 lilv_plugin_get_latency_port_index(const LilvPlugin* p);
 
 /**
-   Get a port on @a plugin by @a index.
+   Get a port on `plugin` by `index`.
 */
 LILV_API const LilvPort*
 lilv_plugin_get_port_by_index(const LilvPlugin* plugin,
                               uint32_t          index);
 
 /**
-   Get a port on @a plugin by @a symbol.
+   Get a port on `plugin` by `symbol`.
    Note this function is slower than lilv_plugin_get_port_by_index,
    especially on plugins with a very large number of ports.
 */
@@ -898,14 +898,14 @@ lilv_plugin_get_port_by_symbol(const LilvPlugin* plugin,
                                const LilvNode*   symbol);
 
 /**
-   Get a port on @c plugin by its lv2:designation.
+   Get a port on `plugin` by its lv2:designation.
 
    The designation of a port describes the meaning, assignment, allocation or
    role of the port, e.g. "left channel" or "gain".  If found, the port with
-   matching @a port_class and @a designation is be returned, otherwise NULL is
-   returned.  The @a port_class can be used to distinguish the input and output
-   ports for a particular designation.  If @a port_class is NULL, any port
-   with the given designation will be returned.
+   matching `port_class` and `designation` is be returned, otherwise NULL is
+   returned.  The `port_class` can be used to distinguish the input and output
+   ports for a particular designation.  If `port_class` is NULL, any port with
+   the given designation will be returned.
 */
 LILV_API const LilvPort*
 lilv_plugin_get_port_by_designation(const LilvPlugin* plugin,
@@ -946,7 +946,7 @@ LILV_API LilvNode*
 lilv_plugin_get_author_homepage(const LilvPlugin* plugin);
 
 /**
-   Return true iff @a plugin has been replaced by another plugin.
+   Return true iff `plugin` has been replaced by another plugin.
 
    The plugin will still be usable, but hosts should hide them from their
    user interfaces to prevent users from using deprecated plugins.
@@ -955,7 +955,7 @@ LILV_API bool
 lilv_plugin_is_replaced(const LilvPlugin* plugin);
 
 /**
-   Write the Turtle description of @c plugin to @c plugin_file.
+   Write the Turtle description of `plugin` to `plugin_file`.
 
    This function is particularly useful for porting plugins in conjunction with
    an LV2 bridge such as NASPRO.
@@ -967,7 +967,7 @@ lilv_plugin_write_description(LilvWorld*        world,
                               FILE*             plugin_file);
 
 /**
-   Write a manifest entry for @c plugin to @c manifest_file.
+   Write a manifest entry for `plugin` to `manifest_file`.
 
    This function is intended for use with lilv_plugin_write_description() to
    write a complete description of a plugin to a bundle.
@@ -980,14 +980,14 @@ lilv_plugin_write_manifest_entry(LilvWorld*        world,
                                  const char*       plugin_file_path);
 
 /**
-   Get the resources related to @c plugin with lv2:appliesTo.
+   Get the resources related to `plugin` with lv2:appliesTo.
 
    Some plugin-related resources are not linked directly to the plugin with
    rdfs:seeAlso and thus will not be automatically loaded along with the plugin
    data (usually for performance reasons).  All such resources of the given @c
-   type related to @c plugin can be accessed with this function.
+   type related to `plugin` can be accessed with this function.
 
-   If @c type is NULL, all such resources will be returned, regardless of type.
+   If `type` is NULL, all such resources will be returned, regardless of type.
 
    To actually load the data for each returned resource, use
    lilv_world_load_resource.
@@ -1002,7 +1002,7 @@ lilv_plugin_get_related(const LilvPlugin* plugin, const LilvNode* type);
 */
 
 /**
-   Get the RDF node of @a port.
+   Get the RDF node of `port`.
 
    Ports nodes may be may be URIs or blank nodes.
 
@@ -1070,7 +1070,7 @@ lilv_port_get_index(const LilvPlugin* plugin,
 /**
    Get the symbol of a port.
    The 'symbol' is a short string, a valid C identifier.
-   Returned value is owned by @a port and must not be freed.
+   Returned value is owned by `port` and must not be freed.
 */
 LILV_API const LilvNode*
 lilv_port_get_symbol(const LilvPlugin* plugin,
@@ -1113,7 +1113,7 @@ lilv_port_is_a(const LilvPlugin* plugin,
 /**
    Get the default, minimum, and maximum values of a port.
 
-   @a def, @a min, and @a max are outputs, pass pointers to uninitialized
+   `def`, `min`, and `max` are outputs, pass pointers to uninitialized
    LilvNode* variables.  These will be set to point at new values (which must
    be freed by the caller using lilv_node_free), or NULL if the value does not
    exist.
@@ -1129,7 +1129,7 @@ lilv_port_get_range(const LilvPlugin* plugin,
    Get the scale points (enumeration values) of a port.
    This returns a collection of 'interesting' named values of a port
    (e.g. appropriate entries for a UI selector associated with this port).
-   Returned value may be NULL if @a port has no scale points, otherwise it
+   Returned value may be NULL if `port` has no scale points, otherwise it
    must be freed by caller with lilv_scale_points_free().
 */
 LILV_API LilvScalePoints*
@@ -1143,7 +1143,7 @@ lilv_port_get_scale_points(const LilvPlugin* plugin,
 */
 
 /**
-   Load a state snapshot from @c world's RDF model.
+   Load a state snapshot from the world RDF model.
    This function can be used to load the default state of a plugin by passing
    the plugin URI as the `subject` parameter.
    @param world The world.
@@ -1164,7 +1164,7 @@ lilv_state_new_from_world(LilvWorld*      world,
    @param path The path of the file containing the state description.
    @return A new LilvState which must be freed with lilv_state_free().
 
-   If @c subject is NULL, it is taken to be the URI of the file (i.e.
+   If `subject` is NULL, it is taken to be the URI of the file (i.e.
    "<>" in Turtle).
 
    This function parses the file separately to create the state, it does not
@@ -1205,19 +1205,19 @@ typedef const void* (*LilvGetPortValueFunc)(const char* port_symbol,
 
    @param plugin The plugin this state applies to.
 
-   @param instance An instance of @c plugin.
+   @param instance An instance of `plugin`.
 
    @param map The map to use for mapping URIs in state.
 
    @param file_dir Directory of files created by the plugin earlier (or NULL).
    This is for hosts that support file creation at any time with state
-   state:makePath.  These files will be copied as necessary to @c copy_dir and
+   state:makePath.  These files will be copied as necessary to `copy_dir` and
    not be referred to directly in state (a temporary directory is appropriate).
 
-   @param copy_dir Directory of copies of files in @c file_dir (or NULL).  This
-   directory will have the same structure as @c file_dir but with possibly
+   @param copy_dir Directory of copies of files in `file_dir` (or NULL).  This
+   directory will have the same structure as `file_dir` but with possibly
    modified file names to distinguish different revisions.  If you only care
-   about saving one state snapshot, it can be the same as @c save_dir.  Plugin
+   about saving one state snapshot, it can be the same as `save_dir`.  Plugin
    state will refer to files in this directory.
 
    @param save_dir Directory of files created by plugin during save (or NULL).
@@ -1253,7 +1253,7 @@ typedef const void* (*LilvGetPortValueFunc)(const char* port_symbol,
    saving an instances state many times while avoiding any duplication of data.
 
    If supported (via state:makePath passed to LV2_Descriptor::instantiate()),
-   @c file_dir should be the directory where any files created by the plugin
+   `file_dir` should be the directory where any files created by the plugin
    (not during save time, e.g. during instantiation) are stored.  These files
    will be copied to preserve their state at this time.plugin-created files are stored.
    Lilv will assume any files within this directory (recursively) are created
@@ -1261,7 +1261,7 @@ typedef const void* (*LilvGetPortValueFunc)(const char* port_symbol,
    does not save the state, use lilv_state_save() for that.
 
    See <a href="http://lv2plug.in/ns/ext/state/state.h">state.h</a> from the
-   LV2 State extension for details on the @c flags and @c features parameters.
+   LV2 State extension for details on the `flags` and `features` parameters.
 */
 LILV_API LilvState*
 lilv_state_new_from_instance(const LilvPlugin*          plugin,
@@ -1277,37 +1277,37 @@ lilv_state_new_from_instance(const LilvPlugin*          plugin,
                              const LV2_Feature *const * features);
 
 /**
-   Free @c state.
+   Free `state`.
 */
 LILV_API void
 lilv_state_free(LilvState* state);
 
 /**
-   Return true iff @c a is equivalent to @c b.
+   Return true iff `a` is equivalent to `b`.
 */
 LILV_API bool
 lilv_state_equals(const LilvState* a, const LilvState* b);
 
 /**
-   Return the number of properties in @c state.
+   Return the number of properties in `state`.
 */
 LILV_API unsigned
 lilv_state_get_num_properties(const LilvState* state);
 
 /**
-   Get the URI of the plugin @c state applies to.
+   Get the URI of the plugin `state` applies to.
 */
 LILV_API const LilvNode*
 lilv_state_get_plugin_uri(const LilvState* state);
 
 /**
-   Get the label of @c state.
+   Get the label of `state`.
 */
 LILV_API const char*
 lilv_state_get_label(const LilvState* state);
 
 /**
-   Set the label of @c state.
+   Set the label of `state`.
 */
 LILV_API void
 lilv_state_set_label(LilvState*  state,
@@ -1330,25 +1330,25 @@ typedef void (*LilvSetPortValueFunc)(const char* port_symbol,
 /**
    Restore a plugin instance from a state snapshot.
    @param state The state to restore, which must apply to the correct plugin.
-   @param instance An instance of the plugin @c state applies to, or NULL.
+   @param instance An instance of the plugin `state` applies to, or NULL.
    @param set_value A function to set a port value (may be NULL).
    @param user_data User data to pass to `set_value`.
    @param flags Bitwise OR of LV2_State_Flags values.
    @param features Features to pass LV2_State_Interface.restore().
 
-   This will set all the properties of @c instance, if given, to the values
-   stored in @c state.  If @c set_value is provided, it will be called (with
-   the given @c user_data) to restore each port value, otherwise the host must
+   This will set all the properties of `instance`, if given, to the values
+   stored in `state`.  If `set_value` is provided, it will be called (with
+   the given `user_data`) to restore each port value, otherwise the host must
    restore the port values itself (using lilv_state_get_port_value) in order to
-   completely restore @c state.
+   completely restore `state`.
 
-   If the state has properties and @c instance is given, this function is in
+   If the state has properties and `instance` is given, this function is in
    the "instantiation" threading class, i.e. it MUST NOT be called
    simultaneously with any function on the same plugin instance.  If the state
-   has no properties, only port values are set via @c set_value.
+   has no properties, only port values are set via `set_value`.
 
    See <a href="http://lv2plug.in/ns/ext/state/state.h">state.h</a> from the
-   LV2 State extension for details on the @c flags and @c features parameters.
+   LV2 State extension for details on the `flags` and `features` parameters.
 */
 LILV_API void
 lilv_state_restore(const LilvState*           state,
@@ -1366,13 +1366,13 @@ lilv_state_restore(const LilvState*           state,
    @param state State to save.
    @param uri URI of state, may be NULL.
    @param dir Path of the bundle directory to save into.
-   @param filename Path of the state file relative to @c dir.
+   @param filename Path of the state file relative to `dir`.
 
    The format of state on disk is compatible with that defined in the LV2
    preset extension, i.e. this function may be used to save presets which can
    be loaded by any host.
 
-   If @c uri is NULL, the preset URI will be a file URI, but the bundle
+   If `uri` is NULL, the preset URI will be a file URI, but the bundle
    can safely be moved (i.e. the state file will use "<>" as the subject).
 */
 LILV_API int
@@ -1412,14 +1412,14 @@ lilv_state_to_string(LilvWorld*       world,
 
 /**
    Get the label of this scale point (enumeration value)
-   Returned value is owned by @a point and must not be freed.
+   Returned value is owned by `point` and must not be freed.
 */
 LILV_API const LilvNode*
 lilv_scale_point_get_label(const LilvScalePoint* point);
 
 /**
    Get the value of this scale point (enumeration value)
-   Returned value is owned by @a point and must not be freed.
+   Returned value is owned by `point` and must not be freed.
 */
 LILV_API const LilvNode*
 lilv_scale_point_get_value(const LilvScalePoint* point);
@@ -1432,7 +1432,7 @@ lilv_scale_point_get_value(const LilvScalePoint* point);
 
 /**
    Get the URI of this class' superclass.
-   Returned value is owned by @a plugin_class and must not be freed by caller.
+   Returned value is owned by `plugin_class` and must not be freed by caller.
    Returned value may be NULL, if class has no parent.
 */
 LILV_API const LilvNode*
@@ -1440,14 +1440,14 @@ lilv_plugin_class_get_parent_uri(const LilvPluginClass* plugin_class);
 
 /**
    Get the URI of this plugin class.
-   Returned value is owned by @a plugin_class and must not be freed by caller.
+   Returned value is owned by `plugin_class` and must not be freed by caller.
 */
 LILV_API const LilvNode*
 lilv_plugin_class_get_uri(const LilvPluginClass* plugin_class);
 
 /**
    Get the label of this plugin class, ie "Oscillators".
-   Returned value is owned by @a plugin_class and must not be freed by caller.
+   Returned value is owned by `plugin_class` and must not be freed by caller.
 */
 LILV_API const LilvNode*
 lilv_plugin_class_get_label(const LilvPluginClass* plugin_class);
@@ -1474,7 +1474,7 @@ lilv_plugin_class_get_children(const LilvPluginClass* plugin_class);
    functions like lilv_instance_run (simple wrappers of functions in lv2.h).
    This is for performance reasons, user code should not use this definition
    in any way (which is why it is not machine documented).
-   Truly private implementation details are hidden via @a ref pimpl.
+   Truly private implementation details are hidden via `pimpl`.
 */
 struct LilvInstanceImpl {
 	const LV2_Descriptor* lv2_descriptor;
@@ -1489,9 +1489,9 @@ struct LilvInstanceImpl {
 /**
    Instantiate a plugin.
    The returned value is a lightweight handle for an LV2 plugin instance,
-   it does not refer to @a plugin, or any other Lilv state.  The caller must
+   it does not refer to `plugin`, or any other Lilv state.  The caller must
    eventually free it with lilv_instance_free().
-   @a features is a NULL-terminated array of features the host supports.
+   `features` is a NULL-terminated array of features the host supports.
    NULL may be passed if the host supports no additional features.
    @return NULL if instantiation failed.
 */
@@ -1503,7 +1503,7 @@ lilv_plugin_instantiate(const LilvPlugin*        plugin,
 /**
    Free a plugin instance.
    It is safe to call this function on NULL.
-   @a instance is invalid after this call.
+   `instance` is invalid after this call.
 */
 LILV_API void
 lilv_instance_free(LilvInstance* instance);
@@ -1511,7 +1511,7 @@ lilv_instance_free(LilvInstance* instance);
 #ifndef LILV_INTERNAL
 
 /**
-   Get the URI of the plugin which @a instance is an instance of.
+   Get the URI of the plugin which `instance` is an instance of.
    Returned string is shared and must not be modified or deleted.
 */
 static inline const char*
@@ -1548,7 +1548,7 @@ lilv_instance_activate(LilvInstance* instance)
 }
 
 /**
-   Run @a instance for @a sample_count frames.
+   Run `instance` for `sample_count` frames.
    If the hint lv2:hardRTCapable is set for this plugin, this function is
    guaranteed not to block.
 */
@@ -1621,8 +1621,8 @@ lilv_instance_get_handle(const LilvInstance* instance)
 */
 
 /**
-   Get all UIs for @a plugin.
-   Returned value must be freed by caller using lilv_uis_free.
+   Get all UIs for `plugin`.
+   Returned value must be freed by caller using lilv_uis_free().
 */
 LILV_API LilvUIs*
 lilv_plugin_get_uis(const LilvPlugin* plugin);
@@ -1658,7 +1658,7 @@ lilv_ui_is_a(const LilvUI* ui, const LilvNode* class_uri);
    Function to determine whether a UI type is supported.
 
    This is provided by the user and must return non-zero iff using a UI of type
-   @c ui_type_uri in a container of type @c container_type_uri is supported.
+   `ui_type_uri` in a container of type `container_type_uri` is supported.
 */
 typedef unsigned (*LilvUISupportedFunc)(const char* container_type_uri,
                                         const char* ui_type_uri);
@@ -1669,8 +1669,8 @@ typedef unsigned (*LilvUISupportedFunc)(const char* container_type_uri,
    @param supported_func User provided supported predicate.
    @param container_type The widget type to host the UI within.
    @param ui_type (Output) If non-NULL, set to the native type of the UI
-   which is owned by @c ui and must not be freed by the caller.
-   @return The embedding quality level returned by @c supported_func.
+   which is owned by `ui` and must not be freed by the caller.
+   @return The embedding quality level returned by `supported_func`.
 */
 LILV_API unsigned
 lilv_ui_is_supported(const LilvUI*       ui,