Use Doxygen Markdown support for more human-readable doc comments.

Minor improvements to UI documentation.

10 files changed, 85 insertions, 82 deletions

diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h
index ec54ef3..3492712 100644
--- a/lv2/lv2plug.in/ns/ext/atom/forge.h
+++ b/lv2/lv2plug.in/ns/ext/atom/forge.h
@@ -128,9 +128,9 @@ static inline void
 lv2_atom_forge_set_buffer(LV2_Atom_Forge* forge, uint8_t* buf, size_t size);
 
 /**
-   Initialise @p forge.
+   Initialise `forge`.
 
-   URIs will be mapped using @p map and stored, a reference to @p map itself is
+   URIs will be mapped using `map` and stored, a reference to `map` itself is
    not held.
 */
 static inline void
@@ -205,7 +205,7 @@ lv2_atom_forge_top_is(LV2_Atom_Forge* forge, uint32_t type)
 		(lv2_atom_forge_deref(forge, forge->stack->ref)->type == type);
 }
 
-/** Return true iff @p type is an atom:Object. */
+/** Return true iff `type` is an atom:Object. */
 static inline bool
 lv2_atom_forge_is_object_type(const LV2_Atom_Forge* forge, uint32_t type)
 {
@@ -214,7 +214,7 @@ lv2_atom_forge_is_object_type(const LV2_Atom_Forge* forge, uint32_t type)
 	        type == forge->Resource);
 }
 
-/** Return true iff @p type is an atom:Object with a blank ID. */
+/** Return true iff `type` is an atom:Object with a blank ID. */
 static inline bool
 lv2_atom_forge_is_blank(const LV2_Atom_Forge*       forge,
                         uint32_t                    type,
@@ -230,7 +230,7 @@ lv2_atom_forge_is_blank(const LV2_Atom_Forge*       forge,
    @{
 */
 
-/** Set the output buffer where @p forge will write atoms. */
+/** Set the output buffer where `forge` will write atoms. */
 static inline void
 lv2_atom_forge_set_buffer(LV2_Atom_Forge* forge, uint8_t* buf, size_t size)
 {
@@ -244,7 +244,7 @@ lv2_atom_forge_set_buffer(LV2_Atom_Forge* forge, uint8_t* buf, size_t size)
 }
 
 /**
-   Set the sink function where @p forge will write output.
+   Set the sink function where `forge` will write output.
 
    The return value of forge functions is an LV2_Atom_Forge_Ref which is an
    integer type safe to use as a pointer but is otherwise opaque.  The sink
@@ -429,7 +429,7 @@ lv2_atom_forge_typed_string(LV2_Atom_Forge* forge,
 	return out;
 }
 
-/** Write an atom:String.  Note that @p str need not be NULL terminated. */
+/** Write an atom:String.  Note that `str` need not be NULL terminated. */
 static inline LV2_Atom_Forge_Ref
 lv2_atom_forge_string(LV2_Atom_Forge* forge, const char* str, uint32_t len)
 {
@@ -437,7 +437,7 @@ lv2_atom_forge_string(LV2_Atom_Forge* forge, const char* str, uint32_t len)
 }
 
 /**
-   Write an atom:URI.  Note that @p uri need not be NULL terminated.
+   Write an atom:URI.  Note that `uri` need not be NULL terminated.
    This does not map the URI, but writes the complete URI string.  To write
    a mapped URI, use lv2_atom_forge_urid().
 */
@@ -447,7 +447,7 @@ lv2_atom_forge_uri(LV2_Atom_Forge* forge, const char* uri, uint32_t len)
 	return lv2_atom_forge_typed_string(forge, forge->URI, uri, len);
 }
 
-/** Write an atom:Path.  Note that @p path need not be NULL terminated. */
+/** Write an atom:Path.  Note that `path` need not be NULL terminated. */
 static inline LV2_Atom_Forge_Ref
 lv2_atom_forge_path(LV2_Atom_Forge* forge, const char* path, uint32_t len)
 {
diff --git a/lv2/lv2plug.in/ns/ext/atom/util.h b/lv2/lv2plug.in/ns/ext/atom/util.h
index 9dc5d32..1340024 100644
--- a/lv2/lv2plug.in/ns/ext/atom/util.h
+++ b/lv2/lv2plug.in/ns/ext/atom/util.h
@@ -44,21 +44,21 @@ lv2_atom_pad_size(uint32_t size)
 	return (size + 7U) & (~7U);
 }
 
-/** Return the total size of @p atom, including the header. */
+/** Return the total size of `atom`, including the header. */
 static inline uint32_t
 lv2_atom_total_size(const LV2_Atom* atom)
 {
 	return (uint32_t)sizeof(LV2_Atom) + atom->size;
 }
 
-/** Return true iff @p atom is null. */
+/** Return true iff `atom` is null. */
 static inline bool
 lv2_atom_is_null(const LV2_Atom* atom)
 {
 	return !atom || (atom->type == 0 && atom->size == 0);
 }
 
-/** Return true iff @p a is equal to @p b. */
+/** Return true iff `a` is equal to `b`. */
 static inline bool
 lv2_atom_equals(const LV2_Atom* a, const LV2_Atom* b)
 {
@@ -86,7 +86,7 @@ lv2_atom_sequence_end(const LV2_Atom_Sequence_Body* body, uint32_t size)
 	return (LV2_Atom_Event*)((const uint8_t*)body + lv2_atom_pad_size(size));
 }
 
-/** Return true iff @p i has reached the end of @p body. */
+/** Return true iff `i` has reached the end of `body`. */
 static inline bool
 lv2_atom_sequence_is_end(const LV2_Atom_Sequence_Body* body,
                          uint32_t                      size,
@@ -95,7 +95,7 @@ lv2_atom_sequence_is_end(const LV2_Atom_Sequence_Body* body,
 	return (const uint8_t*)i >= ((const uint8_t*)body + size);
 }
 
-/** Return an iterator to the element following @p i. */
+/** Return an iterator to the element following `i`. */
 static inline LV2_Atom_Event*
 lv2_atom_sequence_next(const LV2_Atom_Event* i)
 {
@@ -134,7 +134,7 @@ lv2_atom_sequence_next(const LV2_Atom_Event* i)
 */
 
 /**
-   Clear all events from @p sequence.
+   Clear all events from `sequence`.
 
    This simply resets the size field, the other fields are left untouched.
 */
@@ -145,14 +145,14 @@ lv2_atom_sequence_clear(LV2_Atom_Sequence* seq)
 }
 
 /**
-   Append an event at the end of @p sequence.
+   Append an event at the end of `sequence`.
 
    @param seq Sequence to append to.
    @param capacity Total capacity of the sequence atom
    (e.g. as set by the host for sequence output ports).
    @param event Event to write.
 
-   @return A pointer to the newly written event in @p seq,
+   @return A pointer to the newly written event in `seq`,
    or NULL on failure (insufficient space).
 */
 static inline LV2_Atom_Event*
@@ -179,21 +179,21 @@ lv2_atom_sequence_append_event(LV2_Atom_Sequence*    seq,
    @{
 */
 
-/** Get an iterator pointing to the first element in @p tup. */
+/** Get an iterator pointing to the first element in `tup`. */
 static inline LV2_Atom*
 lv2_atom_tuple_begin(const LV2_Atom_Tuple* tup)
 {
 	return (LV2_Atom*)(LV2_ATOM_BODY(tup));
 }
 
-/** Return true iff @p i has reached the end of @p body. */
+/** Return true iff `i` has reached the end of `body`. */
 static inline bool
 lv2_atom_tuple_is_end(const void* body, uint32_t size, const LV2_Atom* i)
 {
 	return (const uint8_t*)i >= ((const uint8_t*)body + size);
 }
 
-/** Return an iterator to the element following @p i. */
+/** Return an iterator to the element following `i`. */
 static inline LV2_Atom*
 lv2_atom_tuple_next(const LV2_Atom* i)
 {
@@ -230,14 +230,14 @@ lv2_atom_tuple_next(const LV2_Atom* i)
    @{
 */
 
-/** Return a pointer to the first property in @p body. */
+/** Return a pointer to the first property in `body`. */
 static inline LV2_Atom_Property_Body*
 lv2_atom_object_begin(const LV2_Atom_Object_Body* body)
 {
 	return (LV2_Atom_Property_Body*)(body + 1);
 }
 
-/** Return true iff @p i has reached the end of @p obj. */
+/** Return true iff `i` has reached the end of `obj`. */
 static inline bool
 lv2_atom_object_is_end(const LV2_Atom_Object_Body*   body,
                        uint32_t                      size,
@@ -246,7 +246,7 @@ lv2_atom_object_is_end(const LV2_Atom_Object_Body*   body,
 	return (const uint8_t*)i >= ((const uint8_t*)body + size);
 }
 
-/** Return an iterator to the property following @p i. */
+/** Return an iterator to the property following `i`. */
 static inline LV2_Atom_Property_Body*
 lv2_atom_object_next(const LV2_Atom_Property_Body* i)
 {
@@ -297,10 +297,10 @@ static const LV2_Atom_Object_Query LV2_ATOM_OBJECT_QUERY_END = { 0, NULL };
 /**
    Get an object's values for various keys.
 
-   The value pointer of each item in @p query will be set to the location of
-   the corresponding value in @p object.  Every value pointer in @p query MUST
-   be initialised to NULL.  This function reads @p object in a single linear
-   sweep.  By allocating @p query on the stack, objects can be "queried"
+   The value pointer of each item in `query` will be set to the location of
+   the corresponding value in `object`.  Every value pointer in `query` MUST
+   be initialised to NULL.  This function reads `object` in a single linear
+   sweep.  By allocating `query` on the stack, objects can be "queried"
    quickly without allocating any memory.  This function is realtime safe.
 
    This function can only do "flat" queries, it is not smart enough to match
diff --git a/lv2/lv2plug.in/ns/ext/log/log.h b/lv2/lv2plug.in/ns/ext/log/log.h
index 2279fa3..d27e549 100644
--- a/lv2/lv2plug.in/ns/ext/log/log.h
+++ b/lv2/lv2plug.in/ns/ext/log/log.h
@@ -69,7 +69,7 @@ typedef struct _LV2_Log {
 
 	   The API of this function matches that of the standard C printf function,
 	   except for the addition of the first two parameters.  This function may
-	   be called from any non-realtime context, or from any context if @p type
+	   be called from any non-realtime context, or from any context if `type`
 	   is @ref LV2_LOG__Trace.
 	*/
 	LV2_LOG_FUNC(3, 4)
@@ -83,7 +83,7 @@ typedef struct _LV2_Log {
 	   The API of this function matches that of the standard C vprintf
 	   function, except for the addition of the first two parameters.  This
 	   function may be called from any non-realtime context, or from any
-	   context if @p type is @ref LV2_LOG__Trace.
+	   context if `type` is @ref LV2_LOG__Trace.
 	*/
 	LV2_LOG_FUNC(3, 0)
 	int (*vprintf)(LV2_Log_Handle handle,
diff --git a/lv2/lv2plug.in/ns/ext/log/logger.h b/lv2/lv2plug.in/ns/ext/log/logger.h
index 88ca0aa..1b03866 100644
--- a/lv2/lv2plug.in/ns/ext/log/logger.h
+++ b/lv2/lv2plug.in/ns/ext/log/logger.h
@@ -49,10 +49,10 @@ typedef struct {
 } LV2_Log_Logger;
 
 /**
-   Initialise @p logger.
+   Initialise `logger`.
 
-   URIs will be mapped using @p map and stored, a reference to @p map itself is
-   not held.  Both @p map and @p log may be NULL when unsupported by the host,
+   URIs will be mapped using `map` and stored, a reference to `map` itself is
+   not held.  Both `map` and `log` may be NULL when unsupported by the host,
    in which case the implementation will fall back to printing to stderr.
 */
 static inline void
diff --git a/lv2/lv2plug.in/ns/ext/midi/midi.h b/lv2/lv2plug.in/ns/ext/midi/midi.h
index 2c53c49..b45b4c2 100644
--- a/lv2/lv2plug.in/ns/ext/midi/midi.h
+++ b/lv2/lv2plug.in/ns/ext/midi/midi.h
@@ -184,7 +184,7 @@ typedef enum {
 } LV2_Midi_Controller;
 
 /**
-   Return true iff @p msg is a MIDI voice message (which has a channel).
+   Return true iff `msg` is a MIDI voice message (which has a channel).
 */
 static inline bool
 lv2_midi_is_voice_message(const uint8_t* msg) {
@@ -192,7 +192,7 @@ lv2_midi_is_voice_message(const uint8_t* msg) {
 }
 
 /**
-   Return true iff @p msg is a MIDI system message (which has no channel).
+   Return true iff `msg` is a MIDI system message (which has no channel).
 */
 static inline bool
 lv2_midi_is_system_message(const uint8_t* msg) {
diff --git a/lv2/lv2plug.in/ns/ext/state/state.h b/lv2/lv2plug.in/ns/ext/state/state.h
index 6d055f5..f701682 100644
--- a/lv2/lv2plug.in/ns/ext/state/state.h
+++ b/lv2/lv2plug.in/ns/ext/state/state.h
@@ -105,11 +105,11 @@ typedef enum {
 /**
    A host-provided function to store a property.
    @param handle Must be the handle passed to LV2_State_Interface.save().
-   @param key The key to store @p value under (URID).
+   @param key The key to store `value` under (URID).
    @param value Pointer to the value to be stored.
-   @param size The size of @p value in bytes.
-   @param type The type of @p value (URID).
-   @param flags LV2_State_Flags for @p value.
+   @param size The size of `value` in bytes.
+   @param type The type of `value` (URID).
+   @param flags LV2_State_Flags for `value`.
    @return 0 on success, otherwise a non-zero error code.
 
    The host passes a callback of this type to LV2_State_Interface.save(). This
@@ -129,8 +129,8 @@ typedef enum {
    (http://lv2plug.in/ns/ext/atom) wherever possible.  The plugin SHOULD
    attempt to fall-back and avoid the error if possible.
 
-   Note that @p size MUST be > 0, and @p value MUST point to a valid region of
-   memory @p size bytes long (this is required to make restore unambiguous).
+   Note that `size` MUST be > 0, and `value` MUST point to a valid region of
+   memory `size` bytes long (this is required to make restore unambiguous).
 
    The plugin MUST NOT attempt to use this function outside of the
    LV2_State_Interface.restore() context.
@@ -151,7 +151,7 @@ typedef LV2_State_Status (*LV2_State_Store_Function)(
    @param type (Output) If non-NULL, set to the type of the restored value.
    @param flags (Output) If non-NULL, set to the flags for the restored value.
    @return A pointer to the restored value (object), or NULL if no value
-   has been stored under @p key.
+   has been stored under `key`.
 
    A callback of this type is passed by the host to
    LV2_State_Interface.restore().  This callback is called repeatedly by the
@@ -188,12 +188,12 @@ typedef const void* (*LV2_State_Retrieve_Function)(
 */
 typedef struct _LV2_State_Interface {
 	/**
-	   Save plugin state using a host-provided @p store callback.
+	   Save plugin state using a host-provided `store` callback.
 
 	   @param instance The instance handle of the plugin.
 	   @param store The host-provided store callback.
 	   @param handle An opaque pointer to host data which MUST be passed as the
-	   handle parameter to @p store if it is called.
+	   handle parameter to `store` if it is called.
 	   @param flags Flags describing desired properties of this save.  These
 	   flags may be used to determine the most appropriate values to store.
 	   @param features Extensible parameter for passing any additional
@@ -204,7 +204,7 @@ typedef struct _LV2_State_Interface {
 	   possible, and consider the possibility of state being restored much
 	   later on a different machine.
 
-	   The @p handle pointer and @p store function MUST NOT be used
+	   The `handle` pointer and `store` function MUST NOT be used
 	   beyond the scope of save().
 
 	   This function has its own special threading class: it may not be called
@@ -230,12 +230,12 @@ typedef struct _LV2_State_Interface {
 	                         const LV2_Feature *const * features);
 
 	/**
-	   Restore plugin state using a host-provided @p retrieve callback.
+	   Restore plugin state using a host-provided `retrieve` callback.
 
 	   @param instance The instance handle of the plugin.
 	   @param retrieve The host-provided retrieve callback.
 	   @param handle An opaque pointer to host data which MUST be passed as the
-	   handle parameter to @p retrieve if it is called.
+	   handle parameter to `retrieve` if it is called.
 	   @param flags Currently unused.
 	   @param features Extensible parameter for passing any additional
 	   features to be used for this restore.
@@ -247,7 +247,7 @@ typedef struct _LV2_State_Interface {
 	   not be retrieved.  This allows the host to reset the plugin state with
 	   an empty map.
 
-	   The @p handle pointer and @p store function MUST NOT be used
+	   The `handle` pointer and `store` function MUST NOT be used
 	   beyond the scope of restore().
 
 	   This function is in the "Instantiation" threading class as defined by
@@ -272,7 +272,7 @@ typedef struct {
 
 	/**
 	   Map an absolute path to an abstract path for use in plugin state.
-	   @param handle MUST be the @p handle member of this struct.
+	   @param handle MUST be the `handle` member of this struct.
 	   @param absolute_path The absolute path of a file.
 	   @return An abstract path suitable for use in plugin state.
 
@@ -294,7 +294,7 @@ typedef struct {
 
 	/**
 	   Map an abstract path from plugin state to an absolute path.
-	   @param handle MUST be the @p handle member of this struct.
+	   @param handle MUST be the `handle` member of this struct.
 	   @param abstract_path An abstract path (e.g. a path from plugin state).
 	   @return An absolute file system path.
 
@@ -320,7 +320,7 @@ typedef struct {
 
 	/**
 	   Return a path the plugin may use to create a new file.
-	   @param handle MUST be the @p handle member of this struct.
+	   @param handle MUST be the `handle` member of this struct.
 	   @param path The path of the new file within a namespace unique to this
 	   plugin instance.
 	   @return The absolute path to use for the new file.
diff --git a/lv2/lv2plug.in/ns/ext/urid/urid.h b/lv2/lv2plug.in/ns/ext/urid/urid.h
index c317f7f..5a308c5 100644
--- a/lv2/lv2plug.in/ns/ext/urid/urid.h
+++ b/lv2/lv2plug.in/ns/ext/urid/urid.h
@@ -106,11 +106,11 @@ typedef struct _LV2_URID_Unmap {
 	/**
 	   Get the URI for a previously mapped numeric ID.
 
-	   Returns NULL if @p urid is not yet mapped.  Otherwise, the corresponding
+	   Returns NULL if `urid` is not yet mapped.  Otherwise, the corresponding
 	   URI is returned in a canonical form.  This MAY not be the exact same
 	   string that was originally passed to LV2_URID_Map::map(), but it MUST be
 	   an identical URI according to the URI syntax specification (RFC3986).  A
-	   non-NULL return for a given @p urid will always be the same for the life
+	   non-NULL return for a given `urid` will always be the same for the life
 	   of the plugin.  Plugins that intend to perform string comparison on
 	   unmapped URIs SHOULD first canonicalise URI strings with a call to
 	   map_uri() followed by a call to unmap_uri().
diff --git a/lv2/lv2plug.in/ns/ext/worker/worker.h b/lv2/lv2plug.in/ns/ext/worker/worker.h
index 00b1039..6c9386b 100644
--- a/lv2/lv2plug.in/ns/ext/worker/worker.h
+++ b/lv2/lv2plug.in/ns/ext/worker/worker.h
@@ -50,7 +50,7 @@ typedef void* LV2_Worker_Respond_Handle;
 /**
    A function to respond to run() from the worker method.
 
-   The @p data MUST be safe for the host to copy and later pass to
+   The `data` MUST be safe for the host to copy and later pass to
    work_response(), and the host MUST guarantee that it will be eventually
    passed to work_response() if this function returns LV2_WORKER_SUCCESS.
 */
@@ -71,14 +71,14 @@ typedef struct _LV2_Worker_Interface {
 	   The worker method.  This is called by the host in a non-realtime context
 	   as requested, possibly with an arbitrary message to handle.
 
-	   A response can be sent to run() using @p respond.  The plugin MUST NOT
+	   A response can be sent to run() using `respond`.  The plugin MUST NOT
 	   make any assumptions about which thread calls this method, other than
 	   the fact that there are no real-time requirements.
 
 	   @param instance The LV2 instance this is a method on.
 	   @param respond  A function for sending a response to run().
-	   @param handle   Must be passed to @p respond if it is called.
-	   @param size     The size of @p data.
+	   @param handle   Must be passed to `respond` if it is called.
+	   @param size     The size of `data`.
 	   @param data     Data from run(), or NULL.
 	*/
 	LV2_Worker_Status (*work)(LV2_Handle                  instance,
@@ -92,7 +92,7 @@ typedef struct _LV2_Worker_Interface {
 	   run() context when a response from the worker is ready.
 
 	   @param instance The LV2 instance this is a method on.
-	   @param size     The size of @p body.
+	   @param size     The size of `body`.
 	   @param body     Message body, or NULL.
 	*/
 	LV2_Worker_Status (*work_response)(LV2_Handle  instance,
@@ -138,12 +138,12 @@ typedef struct _LV2_Worker_Schedule {
 	   immediately, and responses from the worker are delivered immediately,
 	   the effect of the work takes place immediately with sample accuracy.
 
-	   The @p data MUST be safe for the host to copy and later pass to work(),
+	   The `data` MUST be safe for the host to copy and later pass to work(),
 	   and the host MUST guarantee that it will be eventually passed to work()
 	   if this function returns LV2_WORKER_SUCCESS.
 
 	   @param handle The handle field of this struct.
-	   @param size   The size of @p data.
+	   @param size   The size of `data`.
 	   @param data   Message to pass to work(), or NULL.
 	*/
 	LV2_Worker_Status (*schedule_work)(LV2_Worker_Schedule_Handle handle,
diff --git a/lv2/lv2plug.in/ns/extensions/ui/ui.h b/lv2/lv2plug.in/ns/extensions/ui/ui.h
index 91651dd..8fada66 100644
--- a/lv2/lv2plug.in/ns/extensions/ui/ui.h
+++ b/lv2/lv2plug.in/ns/extensions/ui/ui.h
@@ -59,7 +59,7 @@
 #define LV2_UI__windowTitle      LV2_UI_PREFIX "windowTitle"
 
 /**
-   The index returned by LV2_UI_Port_Port::port_index() for unknown ports.
+   The index returned by LV2UI_Port_Map::port_index() for unknown ports.
 */
 #define LV2UI_INVALID_PORT_INDEX ((uint32_t)-1)
 
@@ -98,18 +98,21 @@ typedef void* LV2UI_Feature_Handle;
 /**
    A host-provided function that sends data to a plugin's input ports.
 
-   The @p buffer parameter must point to a block of data, @p buffer_size bytes
-   large.  The format of this data and how the host should use it is defined by
-   the @p port_protocol.  This buffer is owned by the UI and is only valid for
-   the duration of this call.
+   @param controller The opaque controller pointer passed to
+   LV2UI_Descriptor::instantiate().
 
-   The @p port_protocol parameter should either be 0 or the URID for a
-   ui:PortProtocol.  If it is 0, the protocol is implicitly ui:floatProtocol,
-   the port MUST be an lv2:ControlPort input, @p buffer MUST point to a single
-   float value, and @p buffer_size MUST be sizeof(float).
+   @param port_index Index of the port to update.
 
-   The UI SHOULD NOT use a protocol not supported by the host, but the host
-   MUST gracefully ignore any protocol it does not understand.
+   @param buffer Buffer containing `buffer_size` bytes of data.
+
+   @param buffer_size Size of `buffer` in bytes.
+
+   @param port_protocol Either 0 or the URID for a ui:PortProtocol.  If 0, the
+   protocol is implicitly ui:floatProtocol, the port MUST be an lv2:ControlPort
+   input, `buffer` MUST point to a single float value, and `buffer_size` MUST
+   be sizeof(float).  The UI SHOULD NOT use a protocol not supported by the
+   host, but the host MUST gracefully ignore any protocol it does not
+   understand.
 */
 typedef void (*LV2UI_Write_Function)(LV2UI_Controller controller,
                                      uint32_t         port_index,
@@ -143,7 +146,7 @@ typedef struct _LV2UI_Descriptor {
 	   @param write_function A function that the UI can use to send data to the
 	   plugin's input ports.
 
-	   @param controller A handle for the plugin instance to be passed as the
+	   @param controller A handle for the UI instance to be passed as the
 	   first parameter of UI methods.
 
 	   @param widget (output) widget pointer.  The UI points this at its main
@@ -173,18 +176,18 @@ typedef struct _LV2UI_Descriptor {
 	/**
 	   Tell the UI that something interesting has happened at a plugin port.
 
-	   What is "interesting" and how it is written to @p buffer is defined by
-	   @p format, which has the same meaning as in LV2UI_Write_Function().
+	   What is "interesting" and how it is written to `buffer` is defined by
+	   `format`, which has the same meaning as in LV2UI_Write_Function().
 	   Format 0 is a special case for lv2:ControlPort, where this function
 	   should be called when the port value changes (but not necessarily for
-	   every change), @p buffer_size must be sizeof(float), and @p buffer
+	   every change), `buffer_size` must be sizeof(float), and `buffer`
 	   points to a single IEEE-754 float.
 
 	   By default, the host should only call this function for lv2:ControlPort
 	   inputs.  However, the UI can request updates for other ports statically
 	   with ui:portNotification or dynamicaly with ui:portSubscribe.
 
-	   The UI MUST NOT retain any reference to @p buffer after this function
+	   The UI MUST NOT retain any reference to `buffer` after this function
 	   returns, it is only valid for the duration of the call.
 
 	   This member may be NULL if the UI is not interested in any port events.
@@ -247,7 +250,7 @@ typedef struct _LV2UI_Port_Map {
 	LV2UI_Feature_Handle handle;
 
 	/**
-	   Get the index for the port with the given @p symbol.
+	   Get the index for the port with the given `symbol`.
 
 	   @return The index of the port, or LV2UI_INVALID_PORT_INDEX if no such
 	   port is found.
@@ -271,7 +274,7 @@ typedef struct _LV2UI_Port_Subscribe {
 	   This means that the host will call the UI's port_event() function when
 	   the port value changes (as defined by protocol).
 
-	   Calling this function with the same @p port_index and @p port_protocol
+	   Calling this function with the same `port_index` and `port_protocol`
 	   as an already active subscription has no effect.
 
 	   @param handle The handle field of this struct.
@@ -291,7 +294,7 @@ typedef struct _LV2UI_Port_Subscribe {
 	   This means that the host will cease calling calling port_event() when
 	   the port value changes.
 
-	   Calling this function with a @p port_index and @p port_protocol that
+	   Calling this function with a `port_index` and `port_protocol` that
 	   does not refer to an active port subscription has no effect.
 
 	   @param handle The handle field of this struct.
diff --git a/lv2/lv2plug.in/ns/lv2core/lv2.h b/lv2/lv2plug.in/ns/lv2core/lv2.h
index 6e0edaa..a7f9039 100644
--- a/lv2/lv2plug.in/ns/lv2core/lv2.h
+++ b/lv2/lv2plug.in/ns/lv2core/lv2.h
@@ -276,12 +276,12 @@ typedef struct _LV2_Descriptor {
 	   things that the plugin MUST NOT do within the run() function (see
 	   lv2core.ttl for details).
 
-	   As a special case, when @p sample_count == 0, the plugin should update
+	   As a special case, when `sample_count` is 0, the plugin should update
 	   any output ports that represent a single instant in time (e.g. control
 	   ports, but not audio ports). This is particularly useful for latent
 	   plugins, which should update their latency output port so hosts can
 	   pre-roll plugins to compute latency. Plugins MUST NOT crash when
-	   @p sample_count == 0.
+	   `sample_count` is 0.
 
 	   @param instance Instance to be run.
 
@@ -368,9 +368,9 @@ typedef struct _LV2_Descriptor {
    function to find the LV2_Descriptor for the desired plugin.  Plugins are
    accessed by index using values from 0 upwards.  This function MUST return
    NULL for out of range indices, so the host can enumerate plugins by
-   increasing @p index until NULL is returned.
+   increasing `index` until NULL is returned.
 
-   Note that @p index has no meaning, hosts MUST NOT depend on it remaining
+   Note that `index` has no meaning, hosts MUST NOT depend on it remaining
    consistent between loads of the plugin library.
 */
 LV2_SYMBOL_EXPORT