[PATCH wayland 1/4] util: Document wl_array

[Pekka Paalanen]

On Fri, 16 Sep 2016 15:37:36 -0700
Yong Bakos <junk at humanoriented.com> wrote:

> From: Yong Bakos <ybakos at humanoriented.com>
> 
> Add doxygen comments for wl_array and its methods.
> 
> Signed-off-by: Yong Bakos <ybakos at humanoriented.com>
> ---
>  src/wayland-util.h | 66 +++++++++++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 61 insertions(+), 5 deletions(-)
> 
> diff --git a/src/wayland-util.h b/src/wayland-util.h
> index cacc122..fe0507c 100644
> --- a/src/wayland-util.h
> +++ b/src/wayland-util.h
> @@ -206,29 +206,85 @@ wl_list_insert_list(struct wl_list *list, struct wl_list *other);
>  	     pos = tmp,							\
>  	     tmp = wl_container_of(pos->member.prev, tmp, member))
>  
> +/**
> + * \class wl_array
> + *
> + * Dynamic array
> + *

Hi,

we could maybe add a bit more, something like:

A wl_array is a dynamic array that can only grow until completely
released. It is intended for relatively small allocations whose size is
variable or not conveniently known before-hand.

Construction of an array does not require all elements to be of the same
size, but wl_array_for_each() does require all elements to have the same
size.

> + */
>  struct wl_array {
>  	size_t size;
>  	size_t alloc;
>  	void *data;
>  };
>  
> -#define wl_array_for_each(pos, array)					\
> -	for (pos = (array)->data;					\
> -	     (const char *) pos < ((const char *) (array)->data + (array)->size); \
> -	     (pos)++)
> -
> +/**
> + * Initializes the array.
> + *
> + * \param array Array to initialize
> + *
> + * \memberof wl_array
> + */
>  void
>  wl_array_init(struct wl_array *array);
>  
> +/**
> + * Releases the array data.
> + *
> + * \note Leaves the array in an invalid state.
> + *
> + * \param array Array whose data is to be released
> + *
> + * \memberof wl_array
> + */
>  void
>  wl_array_release(struct wl_array *array);
>  
> +/**
> + * Increases the size of the array by \p size bytes.
> + *
> + * \param array Array whose size is to be increased
> + * \param size Number of bytes to increase the size of the array by
> + *
> + * \return A pointer to the beginning of the newly appended space, or NULL when
> + *         resizing fails.
> + *
> + * \memberof wl_array
> + */
>  void *
>  wl_array_add(struct wl_array *array, size_t size);
>  
> +/**
> + * Copies the contents of \p source to \p array.
> + *
> + * \param array Destination array to copy to
> + * \param source Source array to copy from
> + *
> + * \return 0 on success, or -1 on failure
> + *
> + * \memberof wl_array
> + */
>  int
>  wl_array_copy(struct wl_array *array, struct wl_array *source);
>  
> +/**
> + * Iterates over an array.
> + *
> + * This macro expresses a for-each iterator for wl_array. It assigns each
> + * element in the list to \p pos, which can then be referenced in a trailing

s/list/array/

> + * code block.
> + *
> + * \param pos Cursor that each array element will be assigned to

'pos' needs to be a pointer to the array element type, and all elements
in the array must be of the same type and size. That could be
emphasized better.

> + * \param array Array to iterate over
> + *
> + * \relates wl_array
> + * \sa wl_list_for_each()
> + */
> +#define wl_array_for_each(pos, array)					\
> +	for (pos = (array)->data;					\
> +	     (const char *) pos < ((const char *) (array)->data + (array)->size); \
> +	     (pos)++)
> +
>  typedef int32_t wl_fixed_t;
>  
>  static inline double

Good work!


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20160920/a1060f2d/attachment.sig>