Moar inline docs
authorMalte S. Stretz <mss@apache.org>
Tue, 31 Mar 2009 16:01:15 +0000 (16:01 +0000)
committerMalte S. Stretz <mss@apache.org>
Tue, 31 Mar 2009 16:01:15 +0000 (16:01 +0000)
src/buf.c
src/dmx.c
src/util/pins.h

index e37ccc6..713f434 100644 (file)
--- a/src/buf.c
+++ b/src/buf.c
@@ -3,13 +3,14 @@
 /*********************************************************************/
 /* Declaration of public global variables.                           */
 
-/*
+/**
  * All channel greyscale data is initialized to zero.
- * TODO: Size should be based on N_PAINTER
+ * TODO: Size should be based on N_PAINTER but got to fix the dmx 
+ * code first.
  */
 volatile char buf_gs__[512];
 
-/*
+/**
  * One dot correction for everything.
  */
 #define BUF_DC_MAX 0x3F
index 1260426..bb1c777 100644 (file)
--- a/src/dmx.c
+++ b/src/dmx.c
@@ -72,6 +72,10 @@ static void disable_usart(void);
 /*********************************************************************/
 /* Implementation of public interrupts.                              */
 
+/**
+ * ISR to handle an external interrupt (any edge) and act as an 
+ * input to the state machine.
+ */
 void dmx_int_ext_edge(void)
 {
   switch (state_) {
@@ -111,6 +115,10 @@ err: {
   }
 }
 
+/**
+ * ISR to handle an overflow of a timer and act as an 
+ * input to the state machine.
+ */
 void dmx_int_timer_ovf(void)
 {
   // Disable this interrupt.
@@ -141,6 +149,10 @@ err: {
   }
 }
 
+/**
+ * ISR to handle incoming serial data and act both as an 
+ * input to the state machine and store the new data.
+ */
 void dmx_int_usart_rxc(void)
 {
   // Read USART data (p146).
@@ -208,6 +220,10 @@ end: {
 /*********************************************************************/
 /* Implementation of public functions.                               */
 
+/**
+ * Initializes the peripherals (pins, timer, USART) used by the
+ * DMX parser.
+ */
 void dmx_init(void)
 {
   // Initialize state (register), might be needed (p20) and 
@@ -241,12 +257,18 @@ void dmx_init(void)
   disable_trigger();
 }
 
+/**
+ * Starts parsing of DMX data by enabling the external interrupt.
+ */
 void dmx_exec(void)
 {
   // Just enable the trigger for the pin.
   enable_trigger();
 }
 
+/**
+ * Called by the main loop
+ */
 void dmx_update(void)
 {
   mcu_debug_set(error_);
index 233c4b2..57bba0c 100644 (file)
@@ -6,23 +6,38 @@
 
 //////////////////////////////////////////
 
+/**
+ * Check if a Pin is set.
+ */
 #define pin_is_set(pp)  (bit_is_set(pin_SFR_PIN(pp), pin_PIN_NUM(pp)))
 
+/**
+ * Set Pin to High level.
+ */
 #define pin_on(pp)      bits_mask_on( pin_SFR_PRT(pp), pin_PIN_VAL(pp))
+/**
+ * Set Pin to Low level.
+ */
 #define pin_off(pp)     bits_mask_off(pin_SFR_PRT(pp), pin_PIN_VAL(pp))
 
+/**
+ * Set Pin as Input.
+ */
 #define pin_in(pp)      bits_mask_off(pin_SFR_DDR(pp), pin_PIN_VAL(pp))
+/**
+ * Set Pin as Output.
+ */
 #define pin_out(pp)     bits_mask_on( pin_SFR_DDR(pp), pin_PIN_VAL(pp))
 
 //////////////////////////////////////////
-
+// Beware of the precompiler magic, here art dragons!
+// Helper macros to split the X,Y definitions to two separate
+// arguments.
 #define pin_pin(pp)  pin_PIN_NUM(pp)
 #define pin_inr(pp)  pin_SFR_PIN(pp)
 #define pin_outr(pp) pin_SFR_PRT(pp)
 #define pin_ddr(pp)  pin_SFR_DDR(pp)
-
-//////////////////////////////////////////
-
+// Glue together and cut out parts of the definitions.
 #define pin_PIN_NUM(port, pin) pin
 #define pin_PIN_VAL(port, pin) bits_value(pin)
 #define pin_SFR_PIN(port, pin) PIN  ## port