From 1c67d8123580b5cf70b5530277ad8320e97174cd Mon Sep 17 00:00:00 2001 From: David Robillard Date: Thu, 31 Jul 2014 20:39:26 +0000 Subject: Use Doxygen Markdown support for more human-readable doc comments. Minor improvements to UI documentation. --- lv2/lv2plug.in/ns/ext/atom/forge.h | 18 +++++++++--------- lv2/lv2plug.in/ns/ext/atom/util.h | 36 +++++++++++++++++------------------ lv2/lv2plug.in/ns/ext/log/log.h | 4 ++-- lv2/lv2plug.in/ns/ext/log/logger.h | 6 +++--- lv2/lv2plug.in/ns/ext/midi/midi.h | 4 ++-- lv2/lv2plug.in/ns/ext/state/state.h | 32 +++++++++++++++---------------- lv2/lv2plug.in/ns/ext/urid/urid.h | 4 ++-- lv2/lv2plug.in/ns/ext/worker/worker.h | 14 +++++++------- 8 files changed, 59 insertions(+), 59 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext') 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, -- cgit v1.2.1