<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Apr 3, 2019 at 8:44 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 03/04/2019 15:10, Joel Sherrill wrote:<br>
><br>
><br>
> On Wed, Apr 3, 2019 at 3:11 AM Sebastian Huber <br>
> <<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a> <br>
> <mailto:<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a>>> wrote:<br>
><br>
> Hello,<br>
><br>
> I rework currently the Doxygen Guidelines in the RTEMS Software<br>
> Engineering manual. I am not sure what we want to do with the<br>
> @brief in<br>
> the @file blocks. For me it is important that each file belongs to a<br>
> group, so an @ingroup should be mandatory. With an @ingroup the<br>
> @brief<br>
> seems to be redundant (the group should have an @brief and a detailed<br>
> description). This is my proposal for the @file blocks:<br>
><br>
> Files<br>
> -----<br>
><br>
> Place an ``@file`` block at the top of each file.  The ``@file``<br>
> block<br>
> should<br>
> precede the license header.  This placement reduces the chance of<br>
> merge<br>
> conflicts in imported third-party code.  The ``@file`` block shall be<br>
> put into<br>
> a group with ``@ingroup``.  The ``@file`` block shall not have<br>
> additional<br>
> content, e.g. a ``@brief`` description.<br>
><br>
> .. code:: c<br>
><br>
>      /**<br>
>       * @file<br>
>       *<br>
>       * @brief RTEMSScoreThread<br>
>       */<br>
><br>
><br>
> The @brief shows up in at least the list of files and table of <br>
> contents when PDF. It should<br>
> be a short English description of the files. I feel STRONGLY that we <br>
> should have an @brief<br>
> and that it is better English than the example above.<br>
><br>
> Here is an example in HTML output of where it is used:<br>
><br>
> <a href="http://www.icu-project.org/apiref/icu4c/files.html" rel="noreferrer" target="_blank">http://www.icu-project.org/apiref/icu4c/files.html</a><br>
><br>
> FWIW the daily built Doxygen is inaccessible so I can't show you what <br>
> it looks like in our<br>
> documentation.<br>
<br>
We have about 5000 files which should be in a group. I don't want to <br>
write prosaic text for each file. </blockquote><div><br></div><div><div>Now you know why we have been using Doxygen as GCI tasks for years.</div><div>More people should mentor GCI to do this type of random, broad clean up.</div><div> </div></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">What about this approach:<br>
<br>
/**<br>
  * @file<br>
  *<br>
  * @ingroup RTEMSScoreThread<br>
  *<br>
  * @brief<br>
  *<br>
  * @copybrief RTEMSScoreThread<br>
  */<br></blockquote><div><br></div><div>This is OK as a default but it shouldn't be the only option. I wouldn't delete</div><div>a comment that was more specific or use that when a more specific </div><div>comment is better.</div><div><br></div><div>We don't want comments to exist just to improve a comments to code ratio.</div><div>They are supposed to be meaningful. IMO the copybrief adds no value to</div><div>the file when reading it. It only adds value when the file is processed and</div><div>you are reading the Doxygen output. So use this as a default but don't </div><div>delete @brief's which are better and this does not stop someone from</div><div>writing a more meaningful brief.</div><div><br></div><div>I still don't know where in the output, text beyond the @brief on a file</div><div>block goes. Any ideas? </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>
-- <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>