From 4371aabcd0267f994a5a54a07a8a6e82857459d4 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Mon, 22 Aug 2022 14:28:07 -0400 Subject: [PATCH] Fix invalid/unusual documentation comment syntax Collectively, these trigger warnings in both Doxygen and clang (-Wdocumentation-unknown-command). Weirdly, @p in doxygen doesn't do anything but print in a fixed-width font anyway, so just use Markdown quotes to replace it which has the same effect (and reads nicer in the source). The use of @param like @p was invalid, so do the same to those. --- jack.h | 4 ++-- metadata.h | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/jack.h b/jack.h index c44605f..5412f6e 100644 --- a/jack.h +++ b/jack.h @@ -119,7 +119,7 @@ char *jack_get_client_name (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; /** * @return pointer to a string representation of the UUID for - * a client named @param name . If no such client exists, return NULL + * a client named `name`. If no such client exists, return NULL * * @param client the client making the request * @param name the name of the client whose UUID is desired @@ -807,7 +807,7 @@ int jack_port_set_alias (jack_port_t *port, const char *alias) JACK_OPTIONAL_WEA int jack_port_unset_alias (jack_port_t *port, const char *alias) JACK_OPTIONAL_WEAK_EXPORT; /* - * Get any aliases known for @port. + * Get any aliases known for `port`. * * @return the number of aliases discovered for the port */ diff --git a/metadata.h b/metadata.h index c9bec36..8bac355 100644 --- a/metadata.h +++ b/metadata.h @@ -128,7 +128,7 @@ typedef struct { * Free a description. * * @param desc a jack_description_t whose associated memory will all be released - * @param free_description_itself if non-zero, then @param desc will also be passed to free() + * @param free_description_itself if non-zero, then `desc` will also be passed to free() */ void jack_free_description (jack_description_t* desc, int free_description_itself); @@ -212,12 +212,12 @@ typedef void (*JackPropertyChangeCallback)(jack_uuid_t subject, void* arg); /** - * Arrange for @p client to call @p callback whenever a property is created, + * Arrange for `client` to call `callback` whenever a property is created, * changed or deleted. * * @param client the JACK client making the request * @param callback the function to be invoked when a property change occurs - * @param arg the argument to be passed to @param callback when it is invoked + * @param arg the argument to be passed to `callback` when it is invoked * * @return 0 success, -1 otherwise. */