> -----Original Message----- > From: ext Ola Liljedahl [mailto:[email protected]] > Sent: Friday, December 05, 2014 12:27 PM > To: Savolainen, Petri (NSN - FI/Espoo) > Cc: [email protected] > Subject: Re: [lng-odp] Doxygen @param in/out tags > > 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).
The opaque data modified inside the function is significant to the implementation (or object state), but it's not output for the user. odp_atomic_store_u32(&atom, 10); E.g. This call does not provide any output to the user (on operation or object state). User can only see the effect of the operation through some other call like: val = odp_atomic_fetch_add_u32(&atom, 1); if(val == 10) ... There would be output to the user, if e.g. the function would have odp_atomic_u32_t **atom parameter and would set *atom to NULL on failure, etc. > > 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. > Yes, that's the purpose of this thread. -Petri _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
