cpu/lpc2387: Fixed doc and attribute of arm_reset

- arm_reset was completely undocumented, even though technical details buried
  deeply in the data sheet of the LPC2387 are involved in the code
- The attribute "naked" is misplaced, it should only be used when no C code
  is present. However, the function consists of C code only
- The attribute "noreturn" has to be used in the declaration [1] of a function,
  not in the implementation. Otherwise the caller is not informed and code using
  the function will not be optimized.

[1]: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html

cpu/lpc2387/cpu.c

@@ -85,13 +85,28 @@ bool install_irq(int IntNumber, void (*HandlerAddr)(void), int Priority)
     }
 }
 
-__attribute__((naked,noreturn)) void arm_reset(void)
+void arm_reset(void)
 {
+    /*
+     * We abuse the watchdog timer for a reset.
+     */
     irq_disable();
-    WDTC = 0x0FFFF;
-    WDMOD = 0x03;
-    WDFEED= 0xAA;
-    WDFEED= 0x55;
+    /* Set the watchdog timeout constant to 0xFFFF */
+    WDTC   = 0xFFFF;
+    /*
+     * Enable watchdog interrupt and enable reset on watchdog timeout.
+     * (The reset on watchdog timeout flag is ignored, if interrupt on watchdog
+     * timeout is not set. Thus, we set both. The reset takes precedence over
+     * the interrupt, anyway.)
+     */
+    WDMOD  = 0x03;
+    /*
+     * Feed the watchdog by writing 0xAA followed by 0x55:
+     * Reload the watchdog timer with the value in WDTC (0xFFFF)
+     */
+    WDFEED = 0xAA;
+    WDFEED = 0x55;
+    /* Wait for the watchdog timer to expire, thus performing a reset */
     while(1) {}
 }