change log for rtems (2011-06-21)

[Gedare Bloom]

I'm tending to agree with Sebastian about copy-paste, comment bloat,
and hiding 'important' things. This is another example of catering to
a tool's decision about what is good or not.  I don't see much
usefulness in things like:

+/** This macro defines an offset into the ISF for use in assembly. */
 #define ISF_STACK_FRAME_OFFSET 0x00
+/** This macro defines an offset into the ISF for use in assembly. */
 #define ISF_PSR_OFFSET         CPU_MINIMUM_STACK_FRAME_SIZE + 0x00
+/** This macro defines an offset into the ISF for use in assembly. */
 #define ISF_PC_OFFSET          CPU_MINIMUM_STACK_FRAME_SIZE + 0x04
...

When a single comment at the top would be sufficient to tell someone,
without all the copy-paste (especially such blatant copy-paste).

However, I also agree with Ralf, that if Joel (or anyone) wants to
document things, so be it. But I think such effort should focus on
increasing clarity rather than just removing doxygen warnings.

On Wed, Jun 22, 2011 at 9:15 AM, Joel Sherrill
<joel.sherrill at oarcorp.com> wrote:
> On 06/22/2011 07:09 AM, Sebastian Huber wrote:
>>
>> On 06/22/2011 01:57 PM, Joel Sherrill wrote:
>>>
>>> There were over 4000 warnings in the doxygen log.
>>
>> Then you should better set:
>>
>> WARN_IF_UNDOCUMENTED = NO
>>
> That covers up problems.  I would rather fix the problems and
> improve the documentation over time.
>
> I am not of the cover up warnings school of thought.
>>>
>>> I started nibbling on them. I had some time to kill and wasn't in a mood
>>> to work on something more difficult.
>>>
>>> The sparc is used for the output on the site and it was over 200 of them.
>>> If we want Doxygen, it should be thorough
>>
>> Yes, it should be thorough, but documenting trivial stuff leads only to a
>> lot
>> of copy and paste.  It distracts also from more important things.
>>
> OK. If I had had more time and SPARC documentation, each register would
> have more details.
>
>
> --
> Joel Sherrill, Ph.D.             Director of Research&  Development
> joel.sherrill at OARcorp.com        On-Line Applications Research
> Ask me about RTEMS: a free RTOS  Huntsville AL 35805
>   Support Available             (256) 722-9985
>
>
> _______________________________________________
> rtems-vc mailing list
> rtems-vc at rtems.org
> http://www.rtems.org/mailman/listinfo/rtems-vc
>