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 
+#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,33 +1,49 @@
+/** @file */
+
 #ifndef MUSIC_H
-#define MUSIC_H 
+#define MUSIC_H
 
 #include <stdint.h>
 #include <stdlib.h>
 
 #define NOTE_PAUSE	0xffff	// Pause
-#define NOTE_C		30577 // note C 
-#define NOTE_Db		28862 // note C# / Db 
-#define NOTE_D		27242 // note D 
-#define NOTE_Eb		25713 // note D# / Eb 
-#define NOTE_E		24270 // note E 
-#define NOTE_F		22908 // note F 
-#define NOTE_Gb		21622 // note F# / Gb 
-#define NOTE_G		20408 // note G 
-#define NOTE_Ab		19263 // note G# / Ab 
-#define NOTE_A		18182 // note A 
-#define NOTE_Bb		17161 // note A# / Bb 
-#define NOTE_B		16198 // note B 
+#define NOTE_C		30577 // note C
+#define NOTE_Db		28862 // note C# / Db
+#define NOTE_D		27242 // note D
+#define NOTE_Eb		25713 // note D# / Eb
+#define NOTE_E		24270 // note E
+#define NOTE_F		22908 // note F
+#define NOTE_Gb		21622 // note F# / Gb
+#define NOTE_G		20408 // note G
+#define NOTE_Ab		19263 // note G# / Ab
+#define NOTE_A		18182 // note A
+#define NOTE_Bb		17161 // note A# / Bb
+#define NOTE_B		16198 // note B
 
 #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 
+#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 */