Document the API.

stepmania/src/archutils/Darwin/HIDDevice.h

@@ -52,10 +52,25 @@ private:
 	static void AddElement( const void *value, void *context );
 	
 protected:
+	/*
+	 * Each physical device has zero or more logical devices. If this device allows
+	 * a logical device of type (usagePage, usage), then allocated storage as necessary
+	 * and return true, otherwise, return false.
+	 */
 	virtual bool AddLogicalDevice( int usagePage, int usage ) = 0;
-	virtual void AddElement( int usagePage, int usage, int cookie, const CFDictionaryRef dict ) = 0;
+	
+	/*
+	 * If the most recently added logical device cares about the state of an element of type
+	 * (usagePage, usage), store the cookie.
+	 */
+	virtual void AddElement( int usagePage, int usage, int cookie, const CFDictionaryRef properties ) = 0;
+	
+	/*
+	 * Add any elements to the queue by calling AddElementToQueue() with the stored cookies.
+	 */
 	virtual void Open() = 0;
 	
+	// This adds the element with the given cookie to the queue to be notified of state changes.
 	inline void AddElementToQueue( int cookie )
 	{
 		CALL( m_Queue, addElement, IOHIDElementCookie(cookie), 0 );
@@ -69,6 +84,12 @@ public:
 	inline const RString& GetDescription() const { return m_sDescription; }
 	
 	
+	/*
+	 * Add button presses (or releases) to vPresses for the given cookie. More than one DeviceInput
+	 * can be added at a time. For example, Two axes presses may be generated by a single element.
+	 * The value of the element is passed to determine if this is a push or a release. The time
+	 * is provided as an optimization.
+	 */
 	virtual void GetButtonPresses( vector<pair<DeviceInput, bool> >& vPresses, int cookie,
 				       int value, const RageTimer& now ) const = 0;
 	
@@ -78,6 +99,10 @@ public:
 	 * devices, then it must ensure that AssignIDs does not assign an ID outside of its range.
 	 */
 	virtual int AssignIDs( InputDevice startID ) { return 0; }
+	
+	/*
+	 * Add a device and a description for each logical device.
+	 */
 	virtual void GetDevicesAndDescriptions( vector<InputDevice>& dev, vector<RString>& desc ) const = 0;
 };