I'd like to hijack this in the hope there is a solid answer as why we don't add const on any function argument that is input only - then the code describes its own behaviour and enforces it no need for [in/out] then at all ? I would like to add that reason to the API guide lines
On 5 December 2014 at 06:29, Savolainen, Petri (NSN - FI/Espoo) < [email protected]> wrote: > > > > -----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 > -- *Mike Holmes* Linaro Sr Technical Manager LNG - ODP
_______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
