Google Code In Patches

[Sebastian Huber]

Hello Cynthia,

On 12/09/2012 11:08 PM, Cynthia Rempel wrote:
> Hi,
>
> Google Code In is a project designed to encourage high-schoolers to code.
>
> 1. Unfortunately, the directions for the Doxygen commenting are now so complicated, that high-schoolers would have a hard time understanding them; I'M having problems understanding them and I have a Master's in Computer Science.

yes, unfortunately the description of @brief was wrong in the wiki.  The table 
of content style is only used for classes and files.  Other @brief description 
use paragraphs.

http://www.rtems.org/wiki/index.php/GoogleCodeInProjects#Add_Doxygen_File_Headers

The @brief description of functions was not included in this topic.

>
> 2. Every time anyone submits a Google Code In patch it receives harsh criticism, which defeats the purpose of encouraging young people to code.

If someone has problems to handle critique, then he should better start to 
learn it now.

>
> 3. The purpose for Doxygen comments is different than regular comments: they are used to generate documentation, not make the code more clear. Documentation is often used in safety, and suitability certification processes.
>
> That being said, I simply ask that the directions be simplified.
>
> A positive step for criticism would be simple directions on how to get the comments on the source code to generate documentation that will pass safety and suitability certifications.

Yes, we lack a clear guideline for Doxygen comments.  We should address this 
first.  See also

http://www.rtems.org/pipermail/rtems-devel/2012-December/002207.html

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 18 94 80 741-16
Fax     : +49 89 18 94 80 741-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.