charge_manager: cleanup and document

Remove some runtime assert to reduce code size.
Improve the documentation.

BUG=chromium:670886
BRANCH=none
TEST=make buildall -j

Change-Id: I60bd787fad94779cd978aefa26e0581fb5f6ebef
Reviewed-on: https://chromium-review.googlesource.com/416392
Commit-Ready: Philip Chen <philipchen@chromium.org>
Tested-by: Philip Chen <philipchen@chromium.org>
Reviewed-by: Shawn N <shawnn@chromium.org>

1 files changed, 70 insertions, 16 deletions

diff --git a/include/charge_manager.h b/include/charge_manager.h
index 1082883445..64c8272886 100644
--- a/include/charge_manager.h
+++ b/include/charge_manager.h
@@ -17,7 +17,7 @@
 #define CHARGE_CURRENT_UNINITIALIZED -1
 #define CHARGE_VOLTAGE_UNINITIALIZED -1
 
-/*
+/**
  * Time to delay for detecting the charger type (must be long enough for BC1.2
  * driver to get supplier information and notify charge manager).
  */
@@ -42,7 +42,13 @@ struct charge_port_info {
 	int voltage;
 };
 
-/* Called by charging tasks to update their available charge */
+/**
+ * Called by charging tasks to update their available charge.
+ *
+ * @param supplier		Charge supplier to update.
+ * @param port			Charge port to update.
+ * @param charge		Charge port current / voltage.
+ */
 void charge_manager_update_charge(int supplier,
 				  int port,
 				  struct charge_port_info *charge);
@@ -54,10 +60,15 @@ enum dualrole_capabilities {
 	CAP_DEDICATED,
 };
 
-/* Called by charging tasks to indicate partner dualrole capability change */
+/**
+ * Notify charge_manager of a partner dualrole capability change.
+ *
+ * @param port			Charge port which changed.
+ * @param cap			New port capability.
+ */
 void charge_manager_update_dualrole(int port, enum dualrole_capabilities cap);
 
-/*
+/**
  * Charge ceiling can be set independently by different tasks / functions,
  * for different purposes.
  */
@@ -70,7 +81,14 @@ enum ceil_requestor {
 	CEIL_REQUESTOR_COUNT,
 };
 
-/* Update charge ceiling for a given port / requestor */
+/**
+ * Update charge ceiling for a given port. The ceiling can be set independently
+ * for several requestors, and the min. ceil will be enforced.
+ *
+ * @param port			Charge port to update.
+ * @param requestor		Charge ceiling requestor.
+ * @param ceil			Charge ceiling (mA).
+ */
 void charge_manager_set_ceil(int port, enum ceil_requestor requestor, int ceil);
 
 /*
@@ -83,17 +101,44 @@ void charge_manager_set_ceil(int port, enum ceil_requestor requestor, int ceil);
  */
 void charge_manager_force_ceil(int port, int ceil);
 
-/* Select an 'override port', which is always the preferred charge port */
+/**
+ * Select an 'override port', a port which is always the preferred charge port.
+ *
+ * @param port			Charge port to select as override, or
+ *				OVERRIDE_OFF to select no override port,
+ *				or OVERRIDE_DONT_CHARGE to specific that no
+ *				charge port should be selected.
+ * @return			EC_SUCCESS on success,
+ *				the other ec_error_list status on failure.
+ */
 int charge_manager_set_override(int port);
+
+/**
+ * Get the override port.
+ *
+ * @return	Port number or OVERRIDE_OFF or OVERRIDE_DONT_CHARGE.
+ */
 int charge_manager_get_override(void);
 
-/* Returns the current active charge port, as determined by charge manager */
+/**
+ * Get the current active charge port, as determined by charge manager.
+ *
+ * @return	Current active charge port.
+ */
 int charge_manager_get_active_charge_port(void);
 
-/* Return the power limit (uW) set by charge manager. */
+/**
+ * Get the power limit set by charge manager.
+ *
+ * @return	Power limit (uW).
+ */
 int charge_manager_get_power_limit_uw(void);
 
-/* Return the charger current (mA) value or CHARGE_CURRENT_UNINITIALIZED. */
+/**
+ * Get the charger current (mA) value.
+ *
+ * @return	Charger current (mA) or CHARGE_CURRENT_UNINITIALIZED.
+ */
 int charge_manager_get_charger_current(void);
 
 #ifdef CONFIG_USB_PD_LOGGING
@@ -101,10 +146,16 @@ int charge_manager_get_charger_current(void);
 void charge_manager_save_log(int port);
 #endif
 
-/* Update whether a given port is sourcing current. */
+/**
+ * Update whether a given port is sourcing current.
+ *
+ * @param port		Port number to be updated.
+ * @param enable	0 if the source port is disabled;
+ *			Otherwise the source port is enabled.
+ */
 void charge_manager_source_port(int port, int enable);
 
-/*
+/**
  * Get PD source power data objects.
  *
  * @param src_pdo pointer to the data to return.
@@ -114,13 +165,16 @@ int charge_manager_get_source_pdo(const uint32_t **src_pdo);
 
 /* Board-level callback functions */
 
-/*
- * Set the active charge port. Returns EC_SUCCESS if the charge port is
- * accepted, returns ec_error_list status otherwise.
+/**
+ * Set the passed charge port as active.`
+ *
+ * @param charge_port	Charge port to be enabled.
+ * @return		EC_SUCCESS if the charge port is accepted,
+ *			other ec_error_list status otherwise.
  */
 int board_set_active_charge_port(int charge_port);
 
-/*
+/**
  * Set the charge current limit.
  *
  * @param port PD port.
@@ -132,7 +186,7 @@ int board_set_active_charge_port(int charge_port);
 void board_set_charge_limit(int port, int supplier, int charge_ma,
 			    int max_ma, int charge_mv);
 
-/*
+/**
  * Get whether the port is sourcing power on VBUS.
  *
  * @param port PD port.