[avr-libc-commit] [2506] * doc/api/doxygen.config.in (MARKDOWN_SUPPORT): Turn off markdown

[Joerg Wunsch]

Revision: 2506
          http://svn.sv.gnu.org/viewvc/?view=rev&root=avr-libc&revision=2506
Author:   joerg_wunsch
Date:     2016-02-08 10:05:45 +0000 (Mon, 08 Feb 2016)
Log Message:
-----------
* doc/api/doxygen.config.in (MARKDOWN_SUPPORT): Turn off markdown
support, as it clashes with the use of __FOO__-style macro names.
* include/util/delay.h.in: Rephrase and reformat the documentation
of _delay_ms() and _delay_us().  This fixes the remaining doxygen
warnings.

Modified Paths:
--------------
    trunk/avr-libc/ChangeLog
    trunk/avr-libc/doc/api/doxygen.config.in
    trunk/avr-libc/include/util/delay.h.in

Modified: trunk/avr-libc/ChangeLog
===================================================================
--- trunk/avr-libc/ChangeLog    2016-02-08 09:37:07 UTC (rev 2505)
+++ trunk/avr-libc/ChangeLog    2016-02-08 10:05:45 UTC (rev 2506)
@@ -1,5 +1,13 @@
 2016-02-08  Joerg Wunsch <address@hidden>
 
+       * doc/api/doxygen.config.in (MARKDOWN_SUPPORT): Turn off markdown
+       support, as it clashes with the use of __FOO__-style macro names.
+       * include/util/delay.h.in: Rephrase and reformat the documentation
+       of _delay_ms() and _delay_us().  This fixes the remaining doxygen
+       warnings.
+
+2016-02-08  Joerg Wunsch <address@hidden>
+
        * doc/api/main_page.dox: Update copyright year.
 
 2016-02-07  Joerg Wunsch <address@hidden>

Modified: trunk/avr-libc/doc/api/doxygen.config.in
===================================================================
--- trunk/avr-libc/doc/api/doxygen.config.in    2016-02-08 09:37:07 UTC (rev 
2505)
+++ trunk/avr-libc/doc/api/doxygen.config.in    2016-02-08 10:05:45 UTC (rev 
2506)
@@ -297,7 +297,7 @@
 # case of backward compatibilities issues.
 # The default value is: YES.
 
-MARKDOWN_SUPPORT       = YES
+MARKDOWN_SUPPORT       = NO
 
 # When enabled doxygen tries to link words that correspond to documented
 # classes, or namespaces to their corresponding documentation. Such a link can

Modified: trunk/avr-libc/include/util/delay.h.in
===================================================================
--- trunk/avr-libc/include/util/delay.h.in      2016-02-08 09:37:07 UTC (rev 
2505)
+++ trunk/avr-libc/include/util/delay.h.in      2016-02-08 10:05:45 UTC (rev 
2506)
@@ -134,31 +134,38 @@
    delays up to 6.5535 seconds (independent from CPU frequency).  The
    user will not be informed about decreased resolution.
 
-   If the avr-gcc toolchain has __builtin_avr_delay_cycles(unsigned long)
+   If the avr-gcc toolchain has __builtin_avr_delay_cycles()
    support, maximal possible delay is 4294967.295 ms/ F_CPU in MHz. For
    values greater than the maximal possible delay, overflows results in
    no delay i.e., 0ms.
 
-   Conversion of __us into clock cycles may not always result in integer.
-   By default, the clock cycles rounded up to next integer. This ensures that
-   the user gets atleast __us microseconds of delay.
+   Conversion of \c __ms into clock cycles may not always result in
+   integer.  By default, the clock cycles rounded up to next
+   integer. This ensures that the user gets at least \c __ms
+   microseconds of delay.
 
-   Alternatively, user can define __DELAY_ROUND_DOWN__ and 
__DELAY_ROUND_CLOSEST__
-   to round down and round to closest integer.
+   Alternatively, by defining the macro \c __DELAY_ROUND_DOWN__, or
+   \c __DELAY_ROUND_CLOSEST__, before including this header file, the
+   algorithm can be made to round down, or round to closest integer,
+   respectively.
 
-   Note: The new implementation of _delay_ms(double __ms) with 
-    __builtin_avr_delay_cycles(unsigned long) support is not backward 
compatible. 
-   User can define __DELAY_BACKWARD_COMPATIBLE__ to get a backward compatible 
delay.
-   Also, the backward compatible
-   algorithm will be chosen if the code is compiled in a <em>freestanding
-   environment</em> (GCC option \c -ffreestanding), as the math functions
-   required for rounding are not available to the compiler then.
+   \note
 
+   The implementation of _delay_ms() based on
+   __builtin_avr_delay_cycles() is not backward compatible with older
+   implementations.  In order to get functionality backward compatible
+   with previous versions, the macro \c "__DELAY_BACKWARD_COMPATIBLE__"
+   must be defined before including this header file. Also, the
+   backward compatible algorithm will be chosen if the code is
+   compiled in a <em>freestanding environment</em> (GCC option
+   \c -ffreestanding), as the math functions required for rounding are
+   not available to the compiler then.
+
  */
 void
 _delay_ms(double __ms)
 {
-       double __tmp ; 
+       double __tmp ;
 #if __HAS_DELAY_CYCLES && defined(__OPTIMIZE__) && \
   !defined(__DELAY_BACKWARD_COMPATIBLE__) &&      \
   __STDC_HOSTED__
@@ -216,31 +223,38 @@
    _delay_us() will automatically call _delay_ms() instead.  The user
    will not be informed about this case.
 
-   If the avr-gcc toolchain has __builtin_avr_delay_cycles(unsigned long)
+   If the avr-gcc toolchain has __builtin_avr_delay_cycles()
    support, maximal possible delay is 4294967.295 us/ F_CPU in MHz. For
    values greater than the maximal possible delay, overflow results in
    no delay i.e., 0us.
-  
-   Conversion of __us into clock cycles may not always result in integer.
-   By default, the clock cycles rounded up to next integer. This ensures that
-   the user gets atleast __us microseconds of delay.
 
-   Alternatively, user can define __DELAY_ROUND_DOWN__ and 
__DELAY_ROUND_CLOSEST__
-   to round down and round to closest integer.
- 
-   Note: The new implementation of _delay_us(double __us) with 
-    __builtin_avr_delay_cycles(unsigned long) support is not backward 
compatible.
-   User can define __DELAY_BACKWARD_COMPATIBLE__ to get a backward compatible 
delay.
-   Also, the backward compatible
-   algorithm will be chosen if the code is compiled in a <em>freestanding
-   environment</em> (GCC option \c -ffreestanding), as the math functions
-   required for rounding are not available to the compiler then.
+   Conversion of \c __us into clock cycles may not always result in
+   integer.  By default, the clock cycles rounded up to next
+   integer. This ensures that the user gets at least \c __us
+   microseconds of delay.
 
+   Alternatively, by defining the macro \c __DELAY_ROUND_DOWN__, or
+   \c __DELAY_ROUND_CLOSEST__, before including this header file, the
+   algorithm can be made to round down, or round to closest integer,
+   respectively.
+
+   \note
+
+   The implementation of _delay_ms() based on
+   __builtin_avr_delay_cycles() is not backward compatible with older
+   implementations.  In order to get functionality backward compatible
+   with previous versions, the macro \c __DELAY_BACKWARD_COMPATIBLE__
+   must be defined before including this header file. Also, the
+   backward compatible algorithm will be chosen if the code is
+   compiled in a <em>freestanding environment</em> (GCC option
+   \c -ffreestanding), as the math functions required for rounding are
+   not available to the compiler then.
+
  */
 void
 _delay_us(double __us)
 {
-       double __tmp ; 
+       double __tmp ;
 #if __HAS_DELAY_CYCLES && defined(__OPTIMIZE__) && \
   !defined(__DELAY_BACKWARD_COMPATIBLE__) &&      \
   __STDC_HOSTED__
@@ -263,7 +277,7 @@
 
 #else
        uint8_t __ticks;
-       double __tmp2 ; 
+       double __tmp2 ;
        __tmp = ((F_CPU) / 3e6) * __us;
        __tmp2 = ((F_CPU) / 4e6) * __us;
        if (__tmp < 1.0)