Doxygen @param and [in], [out] or [in,out]?

[Gedare Bloom]

On Wed, Mar 13, 2019 at 2:55 AM Sebastian Huber <
sebastian.huber at 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.huber at embedded-brains.de
> PGP     : Public key available on request.
>
> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190313/2c25a300/attachment-0002.html>