From e3f28a3feb4d0a2b8256cfca2c3c8d4cc5af2d3d Mon Sep 17 00:00:00 2001
From: shermp <14854761+shermp@users.noreply.github.com>
Date: Wed, 12 Jun 2019 21:19:03 +1200
Subject: [PATCH] Add comments to struct_rw

---
 src/minivhd_struct_rw.c | 43 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/src/minivhd_struct_rw.c b/src/minivhd_struct_rw.c
index b32766f..4974a09 100644
--- a/src/minivhd_struct_rw.c
+++ b/src/minivhd_struct_rw.c
@@ -15,6 +15,14 @@
 static void mvhd_next_buffer_to_struct(void* struct_memb, size_t memb_size, bool req_endian, uint8_t** buffer);
 static void mvhd_next_struct_to_buffer(void* struct_memb, size_t memb_size, bool req_endian, uint8_t** buffer);
 
+/**
+ * \brief Get the next field from a buffer and store it in a struct member, converting endian if necessary
+ * 
+ * \param [out] struct_memb struct member to save the field to
+ * \param [in] memb_size the size of struct_memb, in bytes
+ * \param [in] req_endian is the field a value that requires endian conversion (eg: uint16, uint32)
+ * \param [in] buffer the buffer from which fields are read from. Will be advanced at the end of the function call
+ */
 static void mvhd_next_buffer_to_struct(void* struct_memb, size_t memb_size, bool req_endian, uint8_t** buffer) {
     memcpy(struct_memb, *buffer, memb_size);
     if (req_endian) {
@@ -33,6 +41,14 @@ static void mvhd_next_buffer_to_struct(void* struct_memb, size_t memb_size, bool
     *buffer += memb_size;
 }
 
+/**
+ * \brief Save a struct member into a buffer, converting endian if necessary
+ * 
+ * \param [in] struct_memb struct member read from
+ * \param [in] memb_size the size of struct_memb, in bytes
+ * \param [in] req_endian is the field a value that requires endian conversion (eg: uint16, uint32)
+ * \param [out] buffer the buffer from which struct member is saved to. Will be advanced at the end of the function call
+ */
 static void mvhd_next_struct_to_buffer(void* struct_memb, size_t memb_size, bool req_endian, uint8_t** buffer) {
     memcpy(*buffer, struct_memb, memb_size);
     if (req_endian) {
@@ -51,6 +67,12 @@ static void mvhd_next_struct_to_buffer(void* struct_memb, size_t memb_size, bool
     *buffer += memb_size;
 }
 
+/**
+ * \brief Save the contents of a VHD footer from a buffer to a struct
+ * 
+ * \param [out] footer save contents of buffer into footer
+ * \param [in] buffer VHD footer in raw bytes
+ */
 void mvhd_buffer_to_footer(MVHDFooter* footer, uint8_t* buffer) {
     uint8_t* buff_ptr = buffer;
     mvhd_next_buffer_to_struct(&footer->cookie, sizeof footer->cookie, false, &buff_ptr);
@@ -72,6 +94,13 @@ void mvhd_buffer_to_footer(MVHDFooter* footer, uint8_t* buffer) {
     mvhd_next_buffer_to_struct(&footer->saved_st, sizeof footer->saved_st, false, &buff_ptr);
     mvhd_next_buffer_to_struct(&footer->reserved, sizeof footer->reserved, false, &buff_ptr);
 }
+
+/**
+ * \brief Save the contents of a VHD footer struct to a buffer
+ * 
+ * \param [in] footer save contents of struct into buffer
+ * \param [out] buffer VHD footer in raw bytes
+ */
 void mvhd_footer_to_buffer(MVHDFooter* footer, uint8_t* buffer) {
     uint8_t* buff_ptr = buffer;
     mvhd_next_struct_to_buffer(&footer->cookie, sizeof footer->cookie, false, &buff_ptr);
@@ -93,6 +122,13 @@ void mvhd_footer_to_buffer(MVHDFooter* footer, uint8_t* buffer) {
     mvhd_next_struct_to_buffer(&footer->saved_st, sizeof footer->saved_st, false, &buff_ptr);
     mvhd_next_struct_to_buffer(&footer->reserved, sizeof footer->reserved, false, &buff_ptr);
 }
+
+/**
+ * \brief Save the contents of a VHD sparse header from a buffer to a struct
+ * 
+ * \param [out] header save contents of buffer into header
+ * \param [in] buffer VHD header in raw bytes
+ */
 void mvhd_buffer_to_header(MVHDSparseHeader* header, uint8_t* buffer) {
     uint8_t* buff_ptr = buffer;
     mvhd_next_buffer_to_struct(&header->cookie, sizeof header->cookie, false, &buff_ptr);
@@ -115,6 +151,13 @@ void mvhd_buffer_to_header(MVHDSparseHeader* header, uint8_t* buffer) {
     }
     mvhd_next_buffer_to_struct(&header->reserved_2, sizeof header->reserved_2, false, &buff_ptr);
 }
+
+/**
+ * \brief Save the contents of a VHD sparse header struct to a buffer
+ * 
+ * \param [in] header save contents of struct into buffer
+ * \param [out] buffer VHD sparse header in raw bytes
+ */
 void mvhd_header_to_buffer(MVHDSparseHeader* header, uint8_t* buffer) {
     uint8_t* buff_ptr = buffer;
     mvhd_next_struct_to_buffer(&header->cookie, sizeof header->cookie, false, &buff_ptr);