Skip to content

Commit 31fa684

Browse files
zfieldsCopilot
zfields
and
Copilot
authored
chore: Doc public API in the .h (#153)
* chore: Doc public API in the `.h` * Apply suggestions from code review Co-authored-by: Copilot <[email protected]> --------- Co-authored-by: Copilot <[email protected]>
1 parent 96a8a97 commit 31fa684

File tree

2 files changed

+381
-212
lines changed

2 files changed

+381
-212
lines changed

‎src/Notecard.cpp‎

Lines changed: 4 additions & 212 deletions
Original file line numberDiff line numberDiff line change
@@ -164,8 +164,10 @@ void noteTransactionStop (void) {
164164
/**************************************************************************/
165165
/*!
166166
@brief Platform Initialization for the Notecard.
167-
This function configures system functions to be used
168-
by the Notecard.
167+
168+
This function configures the user agent information and optionally
169+
the default system functions to be used by the Notecard.
170+
169171
@param assignCallbacks
170172
When `true` the system callbacks will be assigned,
171173
when `false` the system callbacks will be cleared.
@@ -194,22 +196,6 @@ Notecard::~Notecard (void)
194196
noteTxn = make_note_txn(nullptr);
195197
}
196198

197-
/**************************************************************************/
198-
/*!
199-
@brief Initialize the Notecard for I2C.
200-
This function configures the Notecard to use the I2C
201-
bus for communication with the host.
202-
@param noteI2c
203-
A platform specific I2C implementation to use for
204-
communicating with the Notecard from the host.
205-
@param i2cAddress
206-
The I2C Address to use for the Notecard.
207-
@param i2cMtu
208-
The max length of each message to send from the host
209-
to the Notecard. Used to ensure the messages are sized
210-
appropriately for the host.
211-
*/
212-
/**************************************************************************/
213199
void Notecard::begin(NoteI2c * noteI2c_, uint32_t i2cAddress_, uint32_t i2cMtu_)
214200
{
215201
noteI2c = noteI2c_;
@@ -224,16 +210,6 @@ void Notecard::begin(NoteI2c * noteI2c_, uint32_t i2cAddress_, uint32_t i2cMtu_)
224210
}
225211
}
226212

227-
/**************************************************************************/
228-
/*!
229-
@brief Initialize the Notecard for Serial communication.
230-
This function configures the Notecard to use Serial
231-
for communication with the host.
232-
@param noteSerial
233-
A platform specific serial implementation to use for
234-
communicating with the Notecard from the host.
235-
*/
236-
/**************************************************************************/
237213
void Notecard::begin(NoteSerial * noteSerial_)
238214
{
239215
noteSerial = noteSerial_;
@@ -246,42 +222,16 @@ void Notecard::begin(NoteSerial * noteSerial_)
246222
}
247223
}
248224

249-
/**************************************************************************/
250-
/*!
251-
@brief Periodically show Notecard sync status, returning `TRUE`
252-
if something was displayed to the debug stream.
253-
@param pollFrequencyMs
254-
The frequency to poll the Notecard for sync status.
255-
@param maxLevel
256-
The maximum log level to output to the debug console. Pass
257-
-1 for all.
258-
@return `true` if a pending response was displayed to the debug stream.
259-
*/
260-
/**************************************************************************/
261225
bool Notecard::debugSyncStatus(int pollFrequencyMs, int maxLevel)
262226
{
263227
return NoteDebugSyncStatus(pollFrequencyMs, maxLevel);
264228
}
265229

266-
/**************************************************************************/
267-
/*!
268-
@brief Deletes a `J` JSON response object from memory.
269-
@param rsp
270-
A `J` JSON response object.
271-
*/
272-
/**************************************************************************/
273230
void Notecard::deleteResponse(J *rsp) const
274231
{
275232
NoteDeleteResponse(rsp);
276233
}
277234

278-
/**************************************************************************/
279-
/*!
280-
@brief Deinitialize the Notecard object communication.
281-
This function clears the Notecard object's communication
282-
interfaces, and frees all associated memory.
283-
*/
284-
/**************************************************************************/
285235
void Notecard::end(void)
286236
{
287237
// Clear I2C Interface
@@ -306,16 +256,6 @@ void Notecard::end(void)
306256
platformInit(false);
307257
}
308258

309-
/**************************************************************************/
310-
/*!
311-
@deprecated NoteDebug, which this function wraps, should be treated as an
312-
internal Notecard logging function, used only by the library itself
313-
(note-arduino and note-c) and not its users.
314-
@brief Write a message to the serial debug stream.
315-
@param message
316-
A string to log to the serial debug stream.
317-
*/
318-
/**************************************************************************/
319259
NOTE_ARDUINO_DEPRECATED void Notecard::logDebug(const char *message) const
320260
{
321261
#ifdef NOTE_ARDUINO_NO_DEPRECATED_ATTR
@@ -324,17 +264,6 @@ NOTE_ARDUINO_DEPRECATED void Notecard::logDebug(const char *message) const
324264
NoteDebug(message);
325265
}
326266

327-
/**************************************************************************/
328-
/*!
329-
@deprecated NoteDebug, which this function wraps, should be treated as an
330-
internal Notecard logging function, used only by the library itself
331-
(note-arduino and note-c) and not its users.
332-
@brief Write a formatted message to the serial debug stream.
333-
@param format
334-
A format string to log to the serial debug stream.
335-
@param ... one or more values to interpolate into the format string.
336-
*/
337-
/**************************************************************************/
338267
NOTE_ARDUINO_DEPRECATED void Notecard::logDebugf(const char *format, ...) const
339268
{
340269
char message[256];
@@ -349,125 +278,41 @@ NOTE_ARDUINO_DEPRECATED void Notecard::logDebugf(const char *format, ...) const
349278
NoteDebug(message);
350279
}
351280

352-
/**************************************************************************/
353-
/*!
354-
@brief Creates a new command object for population by the host.
355-
This function accepts a command string (for example, `"note.add"`)
356-
and initializes a JSON Object to return to the host.
357-
@param request
358-
The command name, for example, `note.add`.
359-
@return A `J` JSON Object populated with the request name.
360-
*/
361-
/**************************************************************************/
362281
J *Notecard::newCommand(const char *request) const
363282
{
364283
return NoteNewCommand(request);
365284
}
366285

367-
/**************************************************************************/
368-
/*!
369-
@brief Creates a new request object for population by the host.
370-
This function accepts a request string (for example, `"note.add"`)
371-
and initializes a JSON Object to return to the host.
372-
@param request
373-
The request name, for example, `note.add`.
374-
@return A `J` JSON Object populated with the request name.
375-
*/
376-
/**************************************************************************/
377286
J *Notecard::newRequest(const char *request) const
378287
{
379288
return NoteNewRequest(request);
380289
}
381290

382-
/**************************************************************************/
383-
/*!
384-
@brief Sends a request to the Notecard and returns the JSON Response.
385-
This function takes a populated `J` JSON request object
386-
and sends it to the Notecard.
387-
@param req
388-
A `J` JSON request object.
389-
@return `J` JSON Object with the response from the Notecard.
390-
*/
391-
/**************************************************************************/
392291
J *Notecard::requestAndResponse(J *req) const
393292
{
394293
return NoteRequestResponse(req);
395294
}
396295

397-
/**************************************************************************/
398-
/*!
399-
@brief Sends a request to the Notecard, retrying it on failure until the
400-
provided timeout interval lapses, and returns the JSON response.
401-
@param req
402-
A `J` JSON request object.
403-
@param timeoutSeconds
404-
The timeout interval, in seconds.
405-
@return `J` JSON Object with the response from the Notecard.
406-
*/
407-
/**************************************************************************/
408296
J *Notecard::requestAndResponseWithRetry(J *req, uint32_t timeoutSeconds) const
409297
{
410298
return NoteRequestResponseWithRetry(req, timeoutSeconds);
411299
}
412300

413-
/**************************************************************************/
414-
/*!
415-
@brief Determines if there is an error string present in a response object.
416-
@param rsp
417-
A `J` JSON Response object.
418-
@return `true` if the response object contains an error.
419-
*/
420-
/**************************************************************************/
421301
bool Notecard::responseError(J *rsp) const
422302
{
423303
return NoteResponseError(rsp);
424304
}
425305

426-
/**************************************************************************/
427-
/*!
428-
@brief Sends a request to the Notecard.
429-
This function takes a populated `J` JSON request object
430-
and sends it to the Notecard.
431-
@param req
432-
A `J` JSON request object.
433-
@return `True` if the message was successfully sent to the Notecard,
434-
`False` if there was an error.
435-
*/
436-
/**************************************************************************/
437306
bool Notecard::sendRequest(J *req) const
438307
{
439308
return NoteRequest(req);
440309
}
441310

442-
/**************************************************************************/
443-
/*!
444-
@brief Sends a request to the Notecard, retrying it on failure until the
445-
provided timeout interval lapses.
446-
@param req
447-
A `J` JSON request object.
448-
@param timeoutSeconds
449-
The timeout interval, in seconds.
450-
@return `True` if the message was successfully sent to the Notecard,
451-
`False` if the message couldn't be sent.
452-
*/
453-
/**************************************************************************/
454311
bool Notecard::sendRequestWithRetry(J *req, uint32_t timeoutSeconds) const
455312
{
456313
return NoteRequestWithRetry(req, timeoutSeconds);
457314
}
458315

459-
/**************************************************************************/
460-
/*!
461-
@brief Set the debug output source.
462-
A NoteLog object will be constructed via `make_note_log()`
463-
using a platform specific logging channel (for example, `Serial`
464-
on Arduino). The specified channel will be configured as the
465-
source for debug messages provided to `notecard.logDebug()`.
466-
@param noteLog
467-
A platform specific log implementation to be used for
468-
debug output.
469-
*/
470-
/**************************************************************************/
471316
void Notecard::setDebugOutputStream(NoteLog * noteLog_)
472317
{
473318
noteLog = noteLog_;
@@ -479,71 +324,18 @@ void Notecard::setDebugOutputStream(NoteLog * noteLog_)
479324
}
480325
}
481326

482-
/**************************************************************************/
483-
/*!
484-
@brief Override default memory management and timing functions.
485-
@param mallocHook
486-
A memory allocation hook.
487-
@param freeHook
488-
A memory deallocation hook.
489-
@param delayMsHook
490-
A delay execution hook.
491-
@param getMsHook
492-
A get current time hook.
493-
*/
494-
/**************************************************************************/
495327
void Notecard::setFn(mallocFn mallocHook, freeFn freeHook, delayMsFn delayMsHook, getMsFn getMsHook) {
496328
NoteSetFn(mallocHook, freeHook, delayMsHook, getMsHook);
497329
}
498330

499-
/**************************************************************************/
500-
/*!
501-
@brief Set the lock/unlock functions the Notecard uses for I2C access.
502-
@param lockI2cFn
503-
A user-defined callback that blocks until access to the I2C
504-
bus has become available, then returns with ownership of the
505-
I2C bus.
506-
@param unlockI2cFn
507-
A user-defined callback that releases ownership of the
508-
I2C bus taken during the call to `lockI2cFn()`.
509-
*/
510-
/**************************************************************************/
511331
void Notecard::setFnI2cMutex(mutexFn lockI2cFn_, mutexFn unlockI2cFn_) {
512332
NoteSetFnI2CMutex(lockI2cFn_, unlockI2cFn_);
513333
}
514334

515-
/**************************************************************************/
516-
/*!
517-
@brief Set the lock/unlock functions the host MCU uses to ensure
518-
a complete transaction with the Notecard.
519-
@param lockNoteFn
520-
A user-defined callback that blocks until the Notecard has
521-
completed any previous transactions, then returns with
522-
ownership of the next Notecard transaction.
523-
@param unlockNoteFn
524-
A user-defined callback that releases ownership of the
525-
Notecard transaction taken during the call to `lockNoteFn()`.
526-
*/
527-
/**************************************************************************/
528335
void Notecard::setFnNoteMutex(mutexFn lockNoteFn_, mutexFn unlockNoteFn_) {
529336
NoteSetFnNoteMutex(lockNoteFn_, unlockNoteFn_);
530337
}
531338

532-
/**************************************************************************/
533-
/*!
534-
@brief Set the transaction pins.
535-
A NoteTxn object will be constructed via `make_note_txn()`
536-
using a platform specific tuple of digital I/O pins. The
537-
pins are used to send a request to transact and to listen
538-
for the clear to transact signal. Transaction pins are not
539-
necessary on any legacy Notecards, and are only necessary
540-
for certain Notecard SKUs. The pins allow the Notecard to
541-
inform the host it has had time to awaken from deep sleep
542-
and is ready to process commands.
543-
@param noteTxn
544-
A platform specific tuple of digital I/O pins.
545-
*/
546-
/**************************************************************************/
547339
void Notecard::setTransactionPins(NoteTxn * noteTxn_) {
548340
noteTxn = noteTxn_; // Set global interface
549341
if (noteTxn_) {

0 commit comments

Comments
 (0)