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