Skip to content

Commit 62c71df

Browse files
committed
cbor.h, cborparser.c: Migrate parser documentation.
Not 100% sure of the syntax for documenting struct-members outside of the struct as I'm too used to doing it inline, hopefully this works as expected. :-)
1 parent 5b11fd6 commit 62c71df

File tree

2 files changed

+70
-60
lines changed

2 files changed

+70
-60
lines changed

src/cbor.h

Lines changed: 1 addition & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -318,71 +318,12 @@ enum CborParserIteratorFlags
318318

319319
struct CborValue;
320320

321-
/**
322-
* Defines an interface for abstract document readers. This structure is used
323-
* in conjunction with \ref cbor_parser_init_reader to define how the various
324-
* required operations are to be implemented.
325-
*/
321+
326322
struct CborParserOperations
327323
{
328-
/**
329-
* Determines whether \a len bytes may be read from the reader. This is
330-
* called before \ref read_bytes and \ref transfer_bytes to ensure it is safe
331-
* to read the requested number of bytes from the reader.
332-
*
333-
* \param value The CBOR value being parsed.
334-
*
335-
* \param len The number of bytes sought.
336-
*
337-
* \retval true \a len bytes may be read from the reader.
338-
* \retval false Insufficient data is available to be read at this time.
339-
*/
340324
bool (*can_read_bytes)(const struct CborValue *value, size_t len);
341-
342-
/**
343-
* Reads \a len bytes from the reader starting at \a offset bytes from
344-
* the current read position and copies them to \a dst. The read pointer
345-
* is *NOT* modified by this operation.
346-
*
347-
* \param value The CBOR value being parsed.
348-
*
349-
* \param dst The buffer the read bytes will be copied to.
350-
*
351-
* \param offset The starting position for the read relative to the
352-
* current read position.
353-
*
354-
* \param len The number of bytes sought.
355-
*/
356325
void *(*read_bytes)(const struct CborValue *value, void *dst, size_t offset, size_t len);
357-
358-
/**
359-
* Skips past \a len bytes from the reader without reading them. The read
360-
* pointer is advanced in the process.
361-
*
362-
* \param value The CBOR value being parsed.
363-
*
364-
* \param len The number of bytes skipped.
365-
*/
366326
void (*advance_bytes)(struct CborValue *value, size_t len);
367-
368-
/**
369-
* Overwrite the user-supplied pointer \a userptr with the address where the
370-
* data indicated by \a offset is located, then advance the read pointer
371-
* \a len bytes beyond that point.
372-
*
373-
* This routine is used for accessing strings embedded in CBOR documents
374-
* (both text and binary strings).
375-
*
376-
* \param value The CBOR value being parsed.
377-
*
378-
* \param userptr The pointer that will be updated to reference the location
379-
* of the data in the buffer.
380-
*
381-
* \param offset The starting position for the read relative to the
382-
* current read position.
383-
*
384-
* \param len The number of bytes sought.
385-
*/
386327
CborError (*transfer_string)(struct CborValue *value, const void **userptr, size_t offset, size_t len);
387328
};
388329

src/cborparser.c

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,75 @@
142142
* \endif
143143
*/
144144

145+
/**
146+
* \struct CborParserOperations
147+
*
148+
* Defines an interface for abstract document readers. This structure is used
149+
* in conjunction with \ref cbor_parser_init_reader to define how the various
150+
* required operations are to be implemented.
151+
*
152+
*
153+
* \var CborParserOperations::can_read_bytes
154+
*
155+
* Determines whether \a len bytes may be read from the reader. This is
156+
* called before \ref read_bytes and \ref transfer_bytes to ensure it is safe
157+
* to read the requested number of bytes from the reader.
158+
*
159+
* \param value The CBOR value being parsed.
160+
*
161+
* \param len The number of bytes sought.
162+
*
163+
* \retval true \a len bytes may be read from the reader.
164+
* \retval false Insufficient data is available to be read at this time.
165+
*
166+
*
167+
* \var CborParserOperations::read_bytes
168+
*
169+
* Reads \a len bytes from the reader starting at \a offset bytes from
170+
* the current read position and copies them to \a dst. The read pointer
171+
* is *NOT* modified by this operation.
172+
*
173+
* \param value The CBOR value being parsed.
174+
*
175+
* \param dst The buffer the read bytes will be copied to.
176+
*
177+
* \param offset The starting position for the read relative to the
178+
* current read position.
179+
*
180+
* \param len The number of bytes sought.
181+
*
182+
*
183+
* \var CborParserOperations::advance_bytes
184+
*
185+
* Skips past \a len bytes from the reader without reading them. The read
186+
* pointer is advanced in the process.
187+
*
188+
* \param value The CBOR value being parsed.
189+
*
190+
* \param len The number of bytes skipped.
191+
*
192+
*
193+
* \var CborParserOperations::transfer_string
194+
*
195+
* Overwrite the user-supplied pointer \a userptr with the address where the
196+
* data indicated by \a offset is located, then advance the read pointer
197+
* \a len bytes beyond that point.
198+
*
199+
* This routine is used for accessing strings embedded in CBOR documents
200+
* (both text and binary strings).
201+
*
202+
* \param value The CBOR value being parsed.
203+
*
204+
* \param userptr The pointer that will be updated to reference the location
205+
* of the data in the buffer.
206+
*
207+
* \param offset The starting position for the read relative to the
208+
* current read position.
209+
*
210+
* \param len The number of bytes sought.
211+
*/
212+
213+
145214
static uint64_t extract_number_and_advance(CborValue *it)
146215
{
147216
/* This function is only called after we've verified that the number

0 commit comments

Comments
 (0)