From 2ae4f251a4aa60a3f180668ff6e7b3d429f0b734 Mon Sep 17 00:00:00 2001 From: Hayden Roche Date: Thu, 15 Jun 2023 16:59:06 -0400 Subject: [PATCH] Add backticks to some keywords in Doxygen comments. --- n_request.c | 96 ++++++++++++++++++++++++++--------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/n_request.c b/n_request.c index 56eafb42..b3453636 100644 --- a/n_request.c +++ b/n_request.c @@ -38,15 +38,15 @@ NOTE_C_STATIC bool crcError(char *json, uint16_t shouldBeSeqno); static bool notecardSupportsCrc = false; #endif -/** +/*! * @brief Create a JSON object containing an error message. * - * Create a dynamically allocated J object containing a single string field + * Create a dynamically allocated `J` object containing a single string field * "err" whose value is the passed in error message. * * @param errmsg The error message. * - * @returns A J object with the "err" field populated. + * @returns A `J` object with the "err" field populated. */ static J *errDoc(const char *errmsg) { @@ -62,7 +62,7 @@ static J *errDoc(const char *errmsg) return rspdoc; } -/** +/*! * @brief Suppress showing transaction details. * * @returns Void. @@ -72,7 +72,7 @@ void NoteSuspendTransactionDebug() suppressShowTransactions++; } -/** +/*! * @brief Resume showing transaction details. * * @returns Void. @@ -82,15 +82,15 @@ void NoteResumeTransactionDebug() suppressShowTransactions--; } -/** +/*! * @brief Create a new JSON request. * - * Creates a dynamically allocated J object with one field "req" whose value is - * the passed in request string. + * Creates a dynamically allocated `J` object with one field "req" whose value + * is the passed in request string. * * @param request The name of the request, for example `hub.set`. * - * @returns A J object with the "req" field populated. + * @returns A `J` object with the "req" field populated. */ J *NoteNewRequest(const char *request) { @@ -101,16 +101,16 @@ J *NoteNewRequest(const char *request) return reqdoc; } -/** +/*! * @brief Create a new JSON command. * - * Create a dynamically allocated J object with one field "cmd" whose value is + * Create a dynamically allocated `J` object with one field "cmd" whose value is * the passed in request string. The difference between a command and a request * is that the Notecard does not send a response to commands, only to requests. * * @param request The name of the command (e.g. "hub.set"). * - * @returns A J object with the "cmd" field populated. + * @returns A `J` object with the "cmd" field populated. */ J *NoteNewCommand(const char *request) { @@ -121,7 +121,7 @@ J *NoteNewCommand(const char *request) return reqdoc; } -/** +/*! * @brief Send a request to the Notecard. * * The passed in request object is always freed, regardless of if the request @@ -129,12 +129,12 @@ J *NoteNewCommand(const char *request) * not given back to the user. See NoteRequestResponse if you need to work with * the response. * - * @param req A J request object. + * @param req A `J` request object. * - * @returns True if successful and false if an error occurs (e.g. out of memory - * or the response from the Notecard has an "err" field). If req is a - * command rather than a request, a true return value indicates that - * the command was sent without error. However, since the Notecard + * @returns `true` if successful and `false` if an error occurs (e.g. out of + * memory or the response from the Notecard has an "err" field). If req + * is a command rather than a request, a `true` return value indicates + * that the command was sent without error. However, since the Notecard * sends no response to commands, it does not guarantee that the * command was received and processed by the Notecard. */ @@ -152,7 +152,7 @@ bool NoteRequest(J *req) return success; } -/** +/*! * @brief Send a request to the Notecard, retrying it until it succeeds or it * times out. * @@ -161,12 +161,12 @@ bool NoteRequest(J *req) * not given back to the user. See NoteRequestResponseWithRetry if you need to * work with the response. * - * @param req A J request object. + * @param req A `J` request object. * @param timeoutSeconds Time limit for retires, in seconds, if there is no * response, or if the response contains an I/O error. * - * @returns True if successful and false if an error occurs (e.g. out of memory - * or the response from the Notecard has an "err" field). + * @returns `true` if successful and `false` if an error occurs (e.g. out of + * memory or the response from the Notecard has an "err" field). */ bool NoteRequestWithRetry(J *req, uint32_t timeoutSeconds) { @@ -183,15 +183,15 @@ bool NoteRequestWithRetry(J *req, uint32_t timeoutSeconds) return success; } -/** +/*! * @brief Send a request to the Notecard and return the response. * * The passed in request object is always freed, regardless of if the request * was successful or not. * - * @param req A J request object. + * @param req A `J` request object. * - * @returns A J object with the response or NULL if there was an error sending + * @returns A `J` object with the response or NULL if there was an error sending * the request. */ J *NoteRequestResponse(J *req) @@ -212,18 +212,18 @@ J *NoteRequestResponse(J *req) return rsp; } -/** +/*! * @brief Send a request to the Notecard, retrying it until it succeeds or it * times out, and return the response. * * The passed in request object is always freed, regardless of if the request * was successful or not. * - * @param req A J request object. + * @param req A `J` request object. * @param timeoutSeconds Time limit for retires, in seconds, if there is no * response, or if the response contains an I/O error. * - * @returns A J object with the response or NULL if there was an error sending + * @returns A `J` object with the response or NULL if there was an error sending * the request. */ J *NoteRequestResponseWithRetry(J *req, uint32_t timeoutSeconds) @@ -275,13 +275,13 @@ J *NoteRequestResponseWithRetry(J *req, uint32_t timeoutSeconds) return rsp; } -/** +/*! * @brief Send a request to the Notecard and return the response. * * Unlike NoteRequestResponse, this function expects the request to be a - * valid JSON C-string, rather than a J object. It also returns the response as - * a dynamically allocated JSON C-string. The caller is responsible for freeing - * this string. + * valid JSON C-string, rather than a `J` object. It also returns the response + * as a dynamically allocated JSON C-string. The caller is responsible for + * freeing this string. * * @param req A valid JSON C-string containing the request. * @@ -309,15 +309,15 @@ char *NoteRequestResponseJSON(char *reqJSON) return json; } -/** +/*! * @brief Send a request to the Notecard and return the response. * * This function doesn't free the passed in request object. The caller is * responsible for freeing it. * - * @param req A J request object. + * @param req A `J` request object. * - * @returns A J object with the response or NULL if there was an error sending + * @returns A `J` object with the response or NULL if there was an error sending * the request. */ J *NoteTransaction(J *req) @@ -520,7 +520,7 @@ J *NoteTransaction(J *req) return rspdoc; } -/** +/*! * @brief Mark that a reset will be required before doing further I/O on * a given port. * @@ -531,7 +531,7 @@ void NoteResetRequired(void) resetRequired = true; } -/** +/*! * @brief Initialize or re-initialize the module. * * @returns True if the reset was successful and false if not. @@ -544,20 +544,20 @@ bool NoteReset(void) return !resetRequired; } -/** +/*! * @brief Check to see if a Notecard error is present in a JSON string. * * @param errstr The string to check for errors. * @param errtype The error substring to search for in errstr. * - * @returns True if errstr contains errtype and false otherwise. + * @returns `true` if errstr contains errtype and `false` otherwise. */ bool NoteErrorContains(const char *errstr, const char *errtype) { return (strstr(errstr, errtype) != NULL); } -/** +/*! * @brief Clean error strings out of the specified buffer. * * Notecard errors are enclosed in {} (e.g. {io} for an I/O error). This @@ -591,7 +591,7 @@ void NoteErrorClean(char *begin) #ifndef NOTE_LOWMEM -/** +/*! * @brief Convert a hex string to a 64-bit unsigned integer. * * @param p The hex string to convert. @@ -624,7 +624,7 @@ uint64_t n_atoh(char *p, int len) return (n); } -/** +/*! * @brief Compute the CRC32 of the passed in buffer. * * Small lookup-table half-byte CRC32 algorithm. See @@ -653,14 +653,14 @@ NOTE_C_STATIC int32_t crc32(const void* data, size_t length) return ~crc; } -/** +/*! * @brief Append a "crc" field to the passed in JSON buffer. * * The "crc" field has a value of the form "SSSS:CCCCCCCC", where SSSS is the * passed in sequence number and CCCCCCCC is the CRC32. * * @param json The JSON buffer to both add the CRC32 to and to compute the - * CRC32 over. + * CRC32 over. * @param seqno A 16-bit sequence number to include as a part of the CRC. * * @returns A dynamically-allocated version of the passed in buffer with the @@ -708,7 +708,7 @@ NOTE_C_STATIC char *crcAdd(char *json, uint16_t seqno) return newJson; } -/** +/*! * @brief Check the passed in JSON for CRC and sequence number errors. * * If the calculated CRC32 doesn't match what's in the buffer, that's an error. @@ -718,11 +718,11 @@ NOTE_C_STATIC char *crcAdd(char *json, uint16_t seqno) * the lack of a CRC field is an error. * * @param json The JSON buffer for which the CRC should be checked. Note that - * the CRC is stripped from the input JSON regardless of whether or - * not there was an error. + * the CRC is stripped from the input JSON regardless of whether or + * not there was an error. * @param shouldBeSeqno The expected sequence number. * - * @returns True if there's an error and false otherwise. + * @returns `true` if there's an error and `false` otherwise. */ NOTE_C_STATIC bool crcError(char *json, uint16_t shouldBeSeqno) {