| Message ID | 20181010083731.31132-1-a@unstable.cc |
|---|---|
| State | Accepted, archived |
| Headers | show |
| Series | [Openvpn-devel] buffer_list: add functions documentation | expand |
Hi, On 10-10-18 10:37, Antonio Quartulli wrote: > bufferlist_* functions have no documentation whatsoever and the name is > not always enough to fully understand what the function is doing. > For this reason and for the sake of having better documented code, add > function doc in buffer.h. Very good, thanks for documenting this! > Signed-off-by: Antonio Quartulli <a@unstable.cc> > --- > > Some doc might be extended and some might be unecessary. > Still I think it is good to start having doc for more helper functions > we have around. > > src/openvpn/buffer.h | 67 ++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 67 insertions(+) > > diff --git a/src/openvpn/buffer.h b/src/openvpn/buffer.h > index cb9e9dff..dbc5bfc3 100644 > --- a/src/openvpn/buffer.h > +++ b/src/openvpn/buffer.h > @@ -1091,26 +1091,93 @@ struct buffer_list > int max_size; /* maximum size list should grow to */ > }; > > +/** > + * Allocate an empty buffer list of capacity \c max_size. > + * > + * @param max_size the capacity of the list to allocate > + * > + * @return the new list > + */ > struct buffer_list *buffer_list_new(const int max_size); > > +/** > + * Frees a buffer list and all the buffers in it. > + * > + * @param ol the list to free > + */ > void buffer_list_free(struct buffer_list *ol); > > +/** > + * Checks if the list is valid and non-empty > + * > + * @param ol the list to check > + * > + * @return true iff \c ol is not NULL and contains at least one buffer > + */ > bool buffer_list_defined(const struct buffer_list *ol); > > +/** > + * Empty the list \c ol and frees all the contained buffers > + * > + * @param ol the list to reset > + */ > void buffer_list_reset(struct buffer_list *ol); > > +/** > + * Allocates and appends a new buffer containing \c str as data to \c ol > + * > + * @param ol the list to append the new buffer to > + * @param str the string to copy into the new buffer > + */ > void buffer_list_push(struct buffer_list *ol, const char *str); > > +/** > + * Allocatea and appends a new buffer containing \c data of length \c size. Typo: allocate*s*. > + * > + * @param ol the list to append the new buffer to > + * @param data the data to copy into the new buffer > + * @param size the length of \c data to copy into the buffer > + * > + * @return the new buffer > + */ > struct buffer_entry *buffer_list_push_data(struct buffer_list *ol, const void *data, size_t size); > > +/** > + * Retrieve the head buffer > + * > + * @param ol the list to retrieve the buffer from > + * > + * @return a pointer to the head buffer or NULL if the list is empty > + */ > struct buffer *buffer_list_peek(struct buffer_list *ol); > > void buffer_list_advance(struct buffer_list *ol, int n); > > void buffer_list_pop(struct buffer_list *ol); > > +/** > + * Aggregates as many buffers as possible from \c bl in a new buffer of maximum > + * length \c max_len . > + * All the aggregated buffers are removed from the list and replaced by the new > + * one, followed by any additional (non-aggregated) data. > + * > + * @param bl the list of buffer to aggregate > + * @param max the maximum length of the aggregated buffer > + */ > void buffer_list_aggregate(struct buffer_list *bl, const size_t max); > > +/** > + * Aggregates as many buffers as possible from \c bl in a new buffer > + * of maximum length \c max_len . \c sep is written after > + * each copied buffer (also after the last one). All the aggregated buffers are > + * removed from the list and replaced by the new one, followed by any additional > + * (non-aggregated) data. > + * Nothing happens if \c max_len is not enough to aggregate at least 2 buffers. > + * > + * @param bl the list of buffer to aggregate > + * @param max_len the maximum length of the aggregated buffer > + * @param sep the separator to put between buffers during aggregation > + */ > void buffer_list_aggregate_separator(struct buffer_list *bl, > const size_t max_len, const char *sep); > > Apart from the typo, this looks good. Acked-by: Steffan Karger <steffan@karger.me> -Steffan
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
Typo spotted by Steffan got fixed during commit.
Your patch has been applied to the following branches
commit e72b2f2ce062c76c6ab658b7ae961f8b81cba307 (master)
commit 61ef9057cda9e1a52786a16e01cd9368fec8a74e (release/2.4)
Author: Antonio Quartulli
Date: Wed Oct 10 16:37:31 2018 +0800
buffer_list: add functions documentation
Signed-off-by: Antonio Quartulli <a@unstable.cc>
Acked-by: Steffan Karger <steffan@karger.me>
Message-Id: <20181010083731.31132-1-a@unstable.cc>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg17701.html
Signed-off-by: David Sommerseth <davids@openvpn.net>
- --
kind regards,
David Sommerseth
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
iQIcBAEBCgAGBQJbxktfAAoJEIbPlEyWcf3yfxAQAJz1fbqVuJ7paqYuj8Fk6smD
HBQ8AcmF08AOt6yN9uWRtYH+558mBYmnv7DxNigJb2InMbmF7stJoLMmJiEAnqKe
WeWpBpK8XAXl10cdm8hMOISkE8fx31fFwW66ZperMYr0dJVvTiPceSWChFoDrWLQ
VgYYVp5UJBQoMR4GwA22MMFLvfwyMyJO+BSKSQ5kyan+dVFD40xPmTWYCi8CgfYI
Ug2vdLfUveHrzvSptDqI8BuJEVcPRjuY9JafoOrGNxBrjxgnnoRkiYRXniRf2Qgl
97pBjCnO1/szbo4rBoMLoqLa/USqCPH6lwXGYLtdVUasw9VL0uAXJPt44h3HiQgG
quVI8X+EpG599RoXjZ+Dw1EBhuGB4WWoSYtCZjH3A/x2uQ5sVoaG5HRP3ixLA+AS
aCu/Lxk1f4jPtqbSmJBdnKbywrqPvvlCYElhYGhD4t7CTzs623+UVwNRNMevgUvq
7JYoPckVxDmPSs6mE3i957rs6qxtpRJXC9gsYsbnnSySNuxsNP/sWMgzu+9fEtNh
qi6eA3DkDvNjf/Js/Nm+T9jTr+/y9Sfg01NtqzeW4KNyJBkxN0/UjpixO8ROTHJa
xD6XYZWOd2KJeQOsCF63ooAseE2lP+rGDdsbO08h6BKaJmjU0t2QYtX22e+b9TFV
aFA7lPtfShxqE4Q/oCOK
=BC92
-----END PGP SIGNATURE-----
diff --git a/src/openvpn/buffer.h b/src/openvpn/buffer.h index cb9e9dff..dbc5bfc3 100644 --- a/src/openvpn/buffer.h +++ b/src/openvpn/buffer.h @@ -1091,26 +1091,93 @@ struct buffer_list int max_size; /* maximum size list should grow to */ }; +/** + * Allocate an empty buffer list of capacity \c max_size. + * + * @param max_size the capacity of the list to allocate + * + * @return the new list + */ struct buffer_list *buffer_list_new(const int max_size); +/** + * Frees a buffer list and all the buffers in it. + * + * @param ol the list to free + */ void buffer_list_free(struct buffer_list *ol); +/** + * Checks if the list is valid and non-empty + * + * @param ol the list to check + * + * @return true iff \c ol is not NULL and contains at least one buffer + */ bool buffer_list_defined(const struct buffer_list *ol); +/** + * Empty the list \c ol and frees all the contained buffers + * + * @param ol the list to reset + */ void buffer_list_reset(struct buffer_list *ol); +/** + * Allocates and appends a new buffer containing \c str as data to \c ol + * + * @param ol the list to append the new buffer to + * @param str the string to copy into the new buffer + */ void buffer_list_push(struct buffer_list *ol, const char *str); +/** + * Allocatea and appends a new buffer containing \c data of length \c size. + * + * @param ol the list to append the new buffer to + * @param data the data to copy into the new buffer + * @param size the length of \c data to copy into the buffer + * + * @return the new buffer + */ struct buffer_entry *buffer_list_push_data(struct buffer_list *ol, const void *data, size_t size); +/** + * Retrieve the head buffer + * + * @param ol the list to retrieve the buffer from + * + * @return a pointer to the head buffer or NULL if the list is empty + */ struct buffer *buffer_list_peek(struct buffer_list *ol); void buffer_list_advance(struct buffer_list *ol, int n); void buffer_list_pop(struct buffer_list *ol); +/** + * Aggregates as many buffers as possible from \c bl in a new buffer of maximum + * length \c max_len . + * All the aggregated buffers are removed from the list and replaced by the new + * one, followed by any additional (non-aggregated) data. + * + * @param bl the list of buffer to aggregate + * @param max the maximum length of the aggregated buffer + */ void buffer_list_aggregate(struct buffer_list *bl, const size_t max); +/** + * Aggregates as many buffers as possible from \c bl in a new buffer + * of maximum length \c max_len . \c sep is written after + * each copied buffer (also after the last one). All the aggregated buffers are + * removed from the list and replaced by the new one, followed by any additional + * (non-aggregated) data. + * Nothing happens if \c max_len is not enough to aggregate at least 2 buffers. + * + * @param bl the list of buffer to aggregate + * @param max_len the maximum length of the aggregated buffer + * @param sep the separator to put between buffers during aggregation + */ void buffer_list_aggregate_separator(struct buffer_list *bl, const size_t max_len, const char *sep);
bufferlist_* functions have no documentation whatsoever and the name is not always enough to fully understand what the function is doing. For this reason and for the sake of having better documented code, add function doc in buffer.h. Signed-off-by: Antonio Quartulli <a@unstable.cc> --- Some doc might be extended and some might be unecessary. Still I think it is good to start having doc for more helper functions we have around. src/openvpn/buffer.h | 67 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+)