Skip to content

Commit

Permalink
Add backticks to some keywords in Doxygen comments.
Browse files Browse the repository at this point in the history
  • Loading branch information
@haydenroche5
haydenroche5 committed Sep 7, 2023
1 parent 9acc514 commit 2ae4f25
Showing 1 changed file with 48 additions and 48 deletions.
96 changes: 48 additions & 48 deletions n_request.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand All @@ -62,7 +62,7 @@ static J *errDoc(const char *errmsg)
return rspdoc;
}

/**
/*!
* @brief Suppress showing transaction details.
*
* @returns Void.
Expand All @@ -72,7 +72,7 @@ void NoteSuspendTransactionDebug()
suppressShowTransactions++;
}

/**
/*!
* @brief Resume showing transaction details.
*
* @returns Void.
Expand All @@ -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)
{
Expand All @@ -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)
{
Expand All @@ -121,20 +121,20 @@ 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
* was successful or not. The response from the Notecard, if any, is freed and
* 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.
*/
Expand All @@ -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.
*
Expand All @@ -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)
{
Expand All @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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.
*
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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.
*
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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)
{
Expand Down

0 comments on commit 2ae4f25

Please sign in to comment.