From 8aee4cb2f2207e93841664814bb1dbfc1347894c Mon Sep 17 00:00:00 2001
From: Dean Camera <dean@fourwalledcubicle.com>
Date: Tue, 25 Aug 2009 13:15:30 +0000
Subject: Add function documentation to the AVRISP project.

---
 Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.c | 53 ++++++++++++++++++-----
 1 file changed, 41 insertions(+), 12 deletions(-)

(limited to 'Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.c')

diff --git a/Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.c b/Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.c
index 61f4a88e6..9914c085e 100644
--- a/Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.c
+++ b/Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.c
@@ -84,24 +84,21 @@ static ParameterItem_t ParameterTable[] =
 	};
 
 
+/** Loads saved non-volatile parameter values from the EEPROM into the parameter table, as needed. */
 void V2Params_LoadEEPROMParamValues(void)
 {
 	/* Target RESET line polarity is a non-volatile value, retrieve current parameter value from EEPROM */
 	V2Params_GetParamFromTable(PARAM_RESET_POLARITY)->ParamValue = eeprom_read_byte(&EEPROM_Rest_Polarity);
 }
 
-static ParameterItem_t* V2Params_GetParamFromTable(uint8_t ParamID)
-{
-	/* Find the parameter in the parameter table if present */
-	for (uint8_t TableIndex = 0; TableIndex < (sizeof(ParameterTable) / sizeof(ParameterTable[0])); TableIndex++)
-	{
-		if (ParamID == ParameterTable[TableIndex].ParamID)
-		  return &ParameterTable[TableIndex];
-	}
-	
-	return NULL;
-}
-
+/** Retrieves the host PC read/write privellages for a given parameter in the parameter table. This should
+ *  be called before calls to \ref V2Params_GetParameterValue() or \ref V2Params_SetParameterValue() when
+ *  getting or setting parameter values in response to requests from the host.
+ *
+ *  \param ParamID  Parameter ID whose privellages are to be retrieved from the table
+ *
+ *  \return Privellages for the requested parameter, as a mask of PARAM_PRIV_* masks
+ */ 
 uint8_t V2Params_GetParameterPrivellages(uint8_t ParamID)
 {
 	ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
@@ -112,6 +109,12 @@ uint8_t V2Params_GetParameterPrivellages(uint8_t ParamID)
 	return ParamInfo->ParamPrivellages;
 }
 
+/** Retrieves the current value for a given parameter in the parameter table.
+ *
+ *  \param ParamID  Parameter ID whose value is to be retrieved from the table
+ *
+ *  \return Current value of the parameter in the table, or 0 if not found
+ */ 
 uint8_t V2Params_GetParameterValue(uint8_t ParamID)
 {
 	ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
@@ -122,6 +125,13 @@ uint8_t V2Params_GetParameterValue(uint8_t ParamID)
 	return ParamInfo->ParamValue;
 }
 
+/** Sets the value for a given parameter in the parameter table.
+ *
+ *  \param ParamID  Parameter ID whose value is to be set in the table
+ *  \param Value  New value to set the parameter to
+ *
+ *  \return Pointer to the associated parameter information from the parameter table if found, NULL otherwise
+ */
 void V2Params_SetParameterValue(uint8_t ParamID, uint8_t Value)
 {
 	ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
@@ -135,3 +145,22 @@ void V2Params_SetParameterValue(uint8_t ParamID, uint8_t Value)
 	if (ParamID == PARAM_RESET_POLARITY)
 	  eeprom_write_byte(&EEPROM_Rest_Polarity, Value);  
 }
+
+/** Retrieves a parameter entry (including ID, value and privellages) from the parameter table that matches the given
+ *  parameter ID.
+ *
+ *  \param ParamID  Parameter ID to find in the table
+ *
+ *  \return Pointer to the associated parameter information from the parameter table if found, NULL otherwise
+ */
+static ParameterItem_t* V2Params_GetParamFromTable(uint8_t ParamID)
+{
+	/* Find the parameter in the parameter table if present */
+	for (uint8_t TableIndex = 0; TableIndex < (sizeof(ParameterTable) / sizeof(ParameterTable[0])); TableIndex++)
+	{
+		if (ParamID == ParameterTable[TableIndex].ParamID)
+		  return &ParameterTable[TableIndex];
+	}
+	
+	return NULL;
+}
-- 
cgit v1.2.3