firmware: port documentation from open document text to inline doxygen

* I mean, srsly?

.gitignore

@@ -25,3 +25,9 @@ fysick
 *~
 
 bestell
+
+
+# doxygen generated files
+firmware/doc/html
+firmware/doc/latex
+firmware/doc/doxygen_sqlite3.db

firmware/include/pentabug/hal.h

@@ -1,9 +1,13 @@
+/** @file */
+
 #ifndef HAL_H
 #define HAL_H
 
 #include <stdint.h>
 
+/** direction constant for LEDs etc */
 #define LEFT		0
+/** direction constant for LEDs etc */
 #define RIGHT		1
 
 #define OFF		0
@@ -25,23 +29,71 @@ void reset_hw(void);
 // WARNING: you should really use button_clicked() instead
 uint8_t button_state(uint8_t btn);
 
-// returns 1 if the button was clicked since the last call to this function or button_reset()
+/**
+ * Returns if the button was clicked since the last call to this
+ * function or button_reset().
+ * @param btn Button (0 or 1)
+ * @return 1 if the button was pressed, 0 else
+ */
 uint8_t button_clicked(uint8_t btn);
+
 void button_reset(uint8_t btn);
 
 // LEDS
 
+/**
+ * Sets LED to state.
+ * @param led Side (LEFT or RIGHT)
+ * @param state State off (0) or on (else)
 void led_set(uint8_t led, uint8_t state);
+
+/**
+ * Switches on the LED on the side specified.
+ * @param led Side (LEFT or RIGHT)
+ */
 void led_on(uint8_t led);
+
+/**
+ * Switches off the LED on the side specified.
+ * @param led Side (LEFT or RIGHT)
+ */
 void led_off(uint8_t led);
+
+/**
+ * Returns the LED state.
+ * @param led Side (LEFT or RIGHT)
+ * @return State (0 for off, 1 for on)
+ */
 uint8_t led_state(uint8_t led);
+
+
+/**
+ * Toggles the LED state.
+ * @param led Side (LEFT or RIGHT)
+ */
 void led_inv(uint8_t led);
 
 // MOTOR
 
+/**
+ * Sets motor to state.
+ * @param state State off (0) or on (else)
+ */
 void motor_set(uint8_t state);
+
+/**
+ * Turns motor on.
+ */
 void motor_on(void);
+
+/**
+ * Turns motor off.
+ */
 void motor_off(void);
+
+/**
+ * Toggles motor state.
+ */
 void motor_inv(void);
 
 // BUZZER
@@ -57,18 +109,40 @@ void buzzer_off(void);
 // IR
 
 // all these functions control whether a 38kHz modulated IR signal is sent
+
+/**
+ * Turns sending of IR signal on.
+ */
 void ir_on(void);
+
+/**
+ * Turns sending of IR signal off.
+ */
 void ir_off(void);
+
+/**
+ * Toggles state of IR signal (sending on or off).
+ */
 void ir_inv(void);
+
+/**
+ * Set IR signal sending to state.
+ * @param state State off (0) or on (else)
+ */
 void ir_set(uint8_t state);
 
-// returns 1 if a 38kHz modulated IR signal is received
+/**
+ * Returns if a signal was received.
+ * @return 1 if yes, 0 else
+ */
 uint8_t ir_recv(void);
 
 // WAITING
 
-// waits the given amount of ms
-// WARNING: the time is actually measured in pentamilliseconds which are similar but not identical to regular milliseconds
+/**
+ * Waits the given amount of ms.
+ * @ms Time in milliseconds (must be below 1500)
+ */
 void wait_ms(uint16_t ms);
 
 // wait the given amount of ticks, see TICKS_PER_MS

firmware/include/pentabug/music.h

@@ -1,3 +1,5 @@
+/** @file */
+
 #ifndef MUSIC_H
 #define MUSIC_H
 
@@ -21,13 +23,27 @@
 #define MLDY_PAUSE	0xfffe	// user defined pause for melody, the next value is the amount of ms to wait
 #define MLDY_LENGTH	0xfffd	// user defined note length for melody, the next value is the "shortness" of the note (1/n)
 
-// plays the note (see defines above) at the given octave until another note is played or the note is stopped
+/**
+ * Plays the note (see defines in header) at the given
+ * octave until another note is played or the note is stopped.
+ * @param note Note as defined by constants (from NOTE_C to NOTE_B)
+ * @param octave Octave
+ */
 void set_note(uint16_t note, uint8_t octave);
 
-// plays a melody consisting of the array of tunes of length len with speed ms for each tune
+/**
+ * Plays a melody consisting of the array of tunes of length len
+ * with speed ms for each tune.
+ * @param melody Array of tunes
+ * @param len Length of that array.
+ * @param octave Octave
+ * @param speed Speed in ms
+ */
 void play_melody(uint16_t melody[], size_t len, uint8_t octave, int speed);
 
-// stop the currently playing note
+/**
+ * Stop the currently playing note.
+ */
 void stop_note(void);
 
 #endif /* MUSIC_H */

firmware/include/pentabug/photons.h

@@ -1,12 +1,25 @@
+/** @file */
+
 #ifndef PHOTONS_H
 #define PHOTONS_H
 
 #include <stdint.h>
 
+/**
+ * Initializes illuminance measuring.
+ */
 void photons_init(void);
 
+/**
+ * Stops illuminance measuring.
+ */
 void photons_stop(void);
 
+
+/**
+ * Returns illuminance measurement.
+ * @return Measurement value (0-255)
+ */
 uint8_t photons_measure(void);
 
 #endif /* PHOTONS_H */