On Wed, Mar 13, 2019 at 2:55 AM Sebastian Huber < sebastian.hu...@embedded-brains.de> wrote:
> On 28/02/2019 15:52, Sebastian Huber wrote: > > Hello, > > > > we agreed to use @param for function parameter documentation: > > > > > https://docs.rtems.org/branches/master/eng/coding-doxygen.html#doxygen-best-practices > > > > > > Do we want to use [in], [out] or [in,out] as well? > > > > If yes, how are [in], [out] or [in,out] used exactly? For example > > consider values passed by reference. Is in > > > > void f(int *a) > > { > > if (*a == 0) { > > *a = 1; > > } > > } > > > > the parameter a an [in,out] parameter? What about > > > > void g(int *a) > > { > > *a = 1; > > } > > > > ? > > > > How can we ensure that this extra information is consistent throughout > > the documentation? > > > > I think we should remove all the [in], [out] or [in,out] stuff. From > > the parameter type it is quite obvious how they are used, e.g. "type > > *param" vs. "const type *param". For passed by value it is clear that > > they are input parameters. Output only use is normally indicated by > > the function name, e.g. "initialize", "set", "create", etc. > > > > In ticket > > http://devel.rtems.org/ticket/3721 > > Jens Schweikhardt proposed the following: > > "1) only pointer parameters are annotated (since scalars are [in] by > language definition) > 2) [in] indicates that the pointer must point to an initialized object (it > may be dereferenced by the directive) > Not just dereferenced, but: (it may be dereferenced and read by the directive). > 3) [out] indicates that the object pointed to may be written by the > directive > (it may be dereferenced and written by the directive.) > 4) [inout] If both 2) and 3) apply." > > I think these are good guidelines. What about annotation of const > pointers? Should they get the [in] annotation which is somewhat redundant? > > These do seem good. I'd just suggest very minor tweaks to ensure consistent terminology is used. I agree it seems unnecessary about the const pointers, which can also be covered by rule #1. > -- > Sebastian Huber, embedded brains GmbH > > Address : Dornierstr. 4, D-82178 Puchheim, Germany > Phone : +49 89 189 47 41-16 > Fax : +49 89 189 47 41-09 > E-Mail : sebastian.hu...@embedded-brains.de > PGP : Public key available on request. > > Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG. > > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
