On 5 December 2014 at 09:21, Savolainen, Petri (NSN - FI/Espoo)
<[email protected]> wrote:
> Hi,
>
> One more time on these @param in/out tags. I think that "out" tag is not
> needed when implementation writes into an opaque struct. User should not
> access that output directly, but use another (access) function for that. The
> "out" tag is only needed (== relevant to the user) when user can access the
> output data directly.
I don't agree (at least not yet). I don't think it is important
whether the user dereferences a pointer directly or whether the user
uses some kind of access function for achieving the same
functionality.
If the data structure (passed by reference, e.g pointer or some kind
of handle) is modified as a part of the defined semantics of the
function (e.g. atomic_store or atomic_add, odp_packet_set_xxx), I
think that parameter should be tagged as [out] (or [in,out] for e.g.
atomic_add).
What does [in] and [out] signify? I think that is the question we need
to answer first or we will argue forever. Since doxygen [in] and [out]
tags do not related to the code on a syntactical level, they are just
there for the convenience of the user and end up in the documentation
as is, we have the power and the responsibility to define what they
mean. My proposed definition is in the previous paragraph.
>
>
> /**
> * Load value of atomic uint32 variable
> * @note Relaxed memory order, cannot be used for synchronization
> *
> * @param atom Pointer to an atomic uint32 variable
> *
> * @return Value of the variable
> */
> static inline uint32_t odp_atomic_load_u32(odp_atomic_u32_t *atom)
> {
> return __atomic_load_n(&atom->v, __ATOMIC_RELAXED);
> }
>
> /**
> * Store value to atomic uint32 variable
> * @note Relaxed memory order, cannot be used for synchronization
> *
> * @param[out] atom Pointer to an atomic uint32 variable
>
> ===> "out" not needed here. Both params are input, since user should use
> odp_atomic_load_u32() to read the value.
>
> * @param val Value to store in the variable
> */
> static inline void odp_atomic_store_u32(odp_atomic_u32_t *atom,
> uint32_t val)
> {
> __atomic_store_n(&atom->v, val, __ATOMIC_RELAXED);
> }
>
>
>
> /**
> * Shared memory block info
> */
> typedef struct odp_shm_info_t {
> const char *name; /**< Block name */
> void *addr; /**< Block address */
> uint64_t size; /**< Block size in bytes */
> uint64_t page_size; /**< Memory page size */
> uint32_t flags; /**< ODP_SHM_* flags */
> } odp_shm_info_t;
>
> /**
> * Shared memory block info
> *
> * @param[in] shm Block handle
> * @param[out] info Block info pointer for output
>
> ===> "out" needed here since the function outputs information to a struct
> specified in the API.
>
> *
> * @return 0 on success, otherwise non-zero
> */
> int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info);
>
>
>
> -Petri
>
>
>
> _______________________________________________
> lng-odp mailing list
> [email protected]
> http://lists.linaro.org/mailman/listinfo/lng-odp
_______________________________________________
lng-odp mailing list
[email protected]
http://lists.linaro.org/mailman/listinfo/lng-odp
