Add documentation for the libcvautomation_funcs.py wrapper

Rename two functions to make sure they don't appear in the documentation

python/libcvautomation_funcs.py

@@ -15,6 +15,14 @@ import libcvautomation_funcs
 If there are any questions, comments, concerns, or suggestions,
 notify the developer at <bspeice@uncc.edu>"""
 
+## \file libcvautomation_funcs.py
+# \brief Libcvautomation wrapper for python
+# \details This source file is designed to give high-level access to libcvautomation using Python. It was modeled after the Bash wrapper, but allows for access to all the extra features of Python.
+# \author Bradlee Speice
+
+## \package libcvautomation_funcs
+# \brief Namespace to contain all of the features needed to use the libcvautomation_funcs wrapper
+
 #-------------------------------------------------------------------------------
 #  Import the libcvautomation library - this should have already been installed
 #-------------------------------------------------------------------------------
@@ -23,10 +31,11 @@ import libcvautomation
 #-------------------------------------------------------------------------------
 #  Set up the logging options
 #-------------------------------------------------------------------------------
+
 from sys import _current_frames() #For getting the function that called us
 import time
 
-def get_caller():
+def _get_caller():
 	current_frame = sys._current_frames().values()[0] #Current frame
 	caller_frame = current_frame.f_back.f_back #Go back two frames to make sure
 											   #we don't get the name of the function that just called us.
@@ -35,7 +44,7 @@ def get_caller():
 	return caller_name
 
 outfile = '/dev/null'
-def out( message ):
+def _log_output( message ):
 	global outfile #Make sure we use the global outfile,
 				   #that people can change it if need be
 
@@ -59,7 +68,7 @@ def out( message ):
 
 X11_display=None #NULL
 
-def check_display():
+def _check_display():
 	global X11_display
 
 	if X11_display is None:
@@ -68,7 +77,7 @@ def check_display():
 	else:
 		return True
 
-def get_display(): #Intended to be unsafe (and a bit faster)-
+def _get_display(): #Intended to be unsafe (and a bit faster)-
 				   #all wrapper functions should use check_display() explicitly
 	global X11_display
 	return X11_display
@@ -76,7 +85,12 @@ def get_display(): #Intended to be unsafe (and a bit faster)-
 #-------------------------------------------------------------------------------
 #  The following two functions are intended to be used on the front-end
 #-------------------------------------------------------------------------------
-	
+
+## \brief Open a display for use in the libcvautomation_funcs
+# \details This opens a display that will be used for every other function in libcvautomation_funcs.py. If you need to open a different display, use \ref libcvautomation_funcs::close_display() and then open the new display that you want.
+# \param display_name The name of the display to open. The default is to open the first available display, which may not specifically be \c :0.
+# \warning You \em must use this function to open a display before any other functions can be used.
+# \returns Return \c True if the display was successfully opened, \c False otherwise
 def open_display( display_name='' ):
 	global X11_display
 	X11_display = libcvautomation.cvaOpenDisplay( display_name )
@@ -86,6 +100,9 @@ def open_display( display_name='' ):
 	else:
 		return False
 
+## \brief Close a display currently in use by libcvautomation_funcs
+# \details This closes the currently open display. All functions used after this will fail unless you open another display. Use \ref libcvautomation_funcs::open_display() to open the new display.
+# \returns Nothing
 def close_display():
 	global X11_display
 	if X11_display is None:
@@ -111,20 +128,24 @@ _libcvautomation_error_location.x = _libcvautomation_error_location.y = -1
 #  Begin the actual wrapper functions
 #-------------------------------------------------------------------------------
 
+## \brief Press a mouse button down
+# \param mouse_button The number of the mouse button to press
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_down( mouse_button = _mouse_button_default ):
-	"""Press a mouse button down, and leave it down."""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button down: ' + mouse_button )
-		out( 'Mouse button down: ' + mouse_button )
 		libcvautomation.xte_mouseDown( get_display(), mouse_button )
 		return True
 	else:
 		#Display not open
 		return False
 
+## \brief Release a mouse button
+# \param mouse_button The number of the mouse button to release
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_up( mouse_button = _mouse_button_default ):
-	"""Release a mouse button."""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button up: ' + mouse_button )
-		out( 'Mouse button up: ' + mouse_button )
 		libcvautomation.xte_mouseUp( get_display(), mouse_button )
 
 		return True
@@ -132,21 +153,28 @@ def mouse_up( mouse_button = _mouse_button_default ):
 		#Display not open
 		return False
 
+## \brief Press and release a mouse button
+# \param mouse_button The number of the mouse button to click
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_click( mouse_button = _mouse_button_default ):
 key_click "Return"
-	"""Click a mouse button where the mouse is currently located"""
+	if _check_display()
-	if check_display()
+		_log_output( 'Mouse button click: ' + mouse_button )
-		out( 'Mouse button click: ' + mouse_button )
 		libcvautomation.xte_clickMouse( get_display(), mouse_button )
 		return True
 	else:
 		#Display not open
 		return False
 
+## \brief Click a mouse button at an absolute location
+# \details Move the mouse to a location given by an x and y coordinate before clicking
+# \param x_coord The X-coordinate to move the mouse to
+# \param y_coord The Y-coordinate to move the mouse to
+# \param mouse_button The mouse button to click after moving
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_click_xy( x_coord, y_coord, mouse_button = _mouse_button_default ):
-	"""Click a mouse button at an absolute coordinate"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button xy click: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button )
-		out( 'Mouse button xy click: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button )
 		current_location = libcvautomation.xte_mouseLocation( get_display() )
 		x_increment = x_coord - current_location.x
 		y_increment = y_coord - current_location.y
@@ -159,10 +187,17 @@ def mouse_click_xy( x_coord, y_coord, mouse_button = _mouse_button_default ):
 		#Display not open
 		return False
 
+## \brief Click a mouse button at a relative location
+# \details Move the mouse horizontally and vertically by an increment, and then click the mouse
+# \param x_inc The increment to move the mouse horizontally
+# \note A positive increment moves the mouse right, a negative increment moves the mouse left
+# \param y_inc The increment to move the mouse vertically
+# \note A positive increment moves the mouse down, a negative increment moves the mouse up
+# \param mouse_button The mouse button to click after moving
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_click_rxy( x_inc, y_inc, mouse_button = _mouse_button_default ):
-	"""Click a mouse button at a location relative to where it currently is at"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button rxy click: x=' + str(x_inc) + ' y=' + str(y_inc) + ' mouse_button=' + mouse_button )
-		out( 'Mouse button rxy click: x=' + str(x_inc) + ' y=' + str(y_inc) + ' mouse_button=' + mouse_button )
 		libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc )
 		libcvautomation.xte_clickMouse( get_display(), mouse_button )
 
@@ -171,13 +206,22 @@ def mouse_click_rxy( x_inc, y_inc, mouse_button = _mouse_button_default ):
 		#Display not open
 		return False
 
+## \brief Click a mouse button on an image inside the root X11 window
+# \details For each image in \c image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded
+# \param image_names List of image names to search for
+# \param search_method The search method to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use the search methods.
+# \param tolerance The tolerance to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use tolerance.
+# \param timeout Wait for \c timeout seconds before giving up the search for \c image_names in the root X11 window.
+# \note \c use_wait must be set to \c True for this parameter to have any effect
+# \param mouse_button The mouse button to click after finding an image
+# \param use_wait Set to \c True to make this function wait \c timeout seconds before giving up finding an image.
+# \note If set to \c False, this function will go through the list of \c image_names once before giving up.
+# \returns Return \c False if the X11 display was not opened before execution or there were no images found, and \c True otherwise
 def mouse_click_image( [image_names], search_method = _search_method_default,
 						tolerance = _tolerance_default, timeout = _timeout_default,
-						mouse_button = _mouse_button_default, use_wait = True,
+						mouse_button = _mouse_button_default, use_wait = True):
-						use_center = True ):
+	if _check_display():
-	"""Click a mouse button on an image inside the root X11 window"""
+		_log_output( 'Mouse button click on image: Images=' + image_names + 
-	if check_display():
-		out( 'Mouse button click on image: Images=' + image_names + 
 				' search_method=' + search_method + ' tolerance=' + tolerance +
 				' timeout=' + _timeout_default + ' mouse_button=' +
 				' use_wait=' + use_wait + ' use_center=' + use_center)
@@ -217,10 +261,12 @@ def mouse_click_image( [image_names], search_method = _search_method_default,
 		return False
 
 
+## \brief Press and release a mouse button twice
+# \param mouse_button The number of the mouse button to click twice
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_doubleclick( mouse_button = _mouse_button_default ):
-	"""Click a mouse button twice where the mouse is currently located"""
+	if _check_display()
-	if check_display()
+		_log_output( 'Mouse button doubleclick: ' + mouse_button )
-		out( 'Mouse button doubleclick: ' + mouse_button )
 		libcvautomation.xte_clickMouse( get_display(), mouse_button )
 
 		return True
@@ -229,10 +275,15 @@ def mouse_doubleclick( mouse_button = _mouse_button_default ):
 		return False
 
 
+## \brief Click a mouse button twice at an absolute location
+# \details Move the mouse to a location given by an x and y coordinate before clicking twice
+# \param x_coord The X-coordinate to move the mouse to
+# \param y_coord The Y-coordinate to move the mouse to
+# \param mouse_button The mouse button to click after moving
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_doubleclick_xy( x_coord, y_coord, mouse_button = _mouse_button_default ):
-	"""Click a mouse button twice at an absolute coordinate"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button xy doubleclick: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button )
-		out( 'Mouse button xy doubleclick: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button )
 		current_location = libcvautomation.xte_mouseLocation( get_display() )
 		x_increment = x_coord - current_location.x
 		y_increment = y_coord - current_location.y
@@ -246,10 +297,17 @@ def mouse_doubleclick_xy( x_coord, y_coord, mouse_button = _mouse_button_default
 		#Display not open
 		return False
 
+## \brief Click a mouse button twice at a relative location
+# \details Move the mouse horizontally and vertically by an increment, and then click the mouse twice
+# \param x_inc The increment to move the mouse horizontally
+# \note A positive increment moves the mouse right, a negative increment moves the mouse left
+# \param y_inc The increment to move the mouse vertically
+# \note A positive increment moves the mouse down, a negative increment moves the mouse up
+# \param mouse_button The mouse button to click after moving
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_doubleclick_rxy( x_inc, y_inc, mouse_button = _mouse_button_default ):
-	"""Click a mouse button twice at a location relative to where it currently is at"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button relative xy doubleclick: x=' + str(x_inc) + ' y=' + str(y_inc) + ' mouse_button=' + mouse_button )
-		out( 'Mouse button relative xy doubleclick: x=' + str(x_inc) + ' y=' + str(y_inc) + ' mouse_button=' + mouse_button )
 		libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc )
 		libcvautomation.xte_clickMouse( get_display(), mouse_button )
 		libcvautomation.xte_clickMouse( get_display(), mouse_button )
@@ -259,13 +317,23 @@ def mouse_doubleclick_rxy( x_inc, y_inc, mouse_button = _mouse_button_default ):
 		#Display not open
 		return False
 
+## \brief Click a mouse button twice on an image inside the root X11 window
+# \details For each image in \c image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded
+# \param image_names List of image names to search for
+# \param search_method The search method to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use the search methods.
+# \param tolerance The tolerance to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use tolerance.
+# \param timeout Wait for \c timeout seconds before giving up the search for \c image_names in the root X11 window.
+# \note \c use_wait must be set to \c True for this parameter to have any effect
+# \param mouse_button The mouse button to click after finding an image
+# \param use_wait Set to \c True to make this function wait \c timeout seconds before giving up finding an image.
+# \note If set to \c False, this function will go through the list of \c image_names once before giving up.
+# \returns Return \c False if the X11 display was not opened before execution or no images were found, and \c True otherwise
 def mouse_doubleclick_image( [image_names], search_method = _search_method_default,
 						tolerance = _tolerance_default, timeout = _timeout_default,
 						mouse_button = _mouse_button_default, use_wait = True,
 						use_center = True ):
-	"""Click a mouse button twice on an image inside the root X11 window"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button doubleclick on image: Images=' + image_names + 
-		out( 'Mouse button doubleclick on image: Images=' + image_names + 
 				' search_method=' + search_method + ' tolerance=' + tolerance +
 				' timeout=' + _timeout_default + ' mouse_button=' +
 				' use_wait=' + use_wait + ' use_center=' + use_center)
@@ -309,10 +377,13 @@ def mouse_doubleclick_image( [image_names], search_method = _search_method_defau
 		#Display not open, or no image found
 		return False
 
+## \brief Move the mouse to a given coordinate, and leave it there
+# \param x_coord The X-coordinate to move the mouse to
+# \param y_coord The Y-coordinate to move the mouse to
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_hover_xy( x_coord, y_coord ):
-	"""Move the mouse to an absolute coordinate"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button hover xy: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button )
-		out( 'Mouse button hover xy: x=' + str(x_coord) + ' y=' + str(y_coord) + ' mouse_button=' + mouse_button )
 		current_location = libcvautomation.xte_mouseLocation( get_display() )
 		x_increment = x_coord - current_location.x
 		y_increment = y_coord - current_location.y
@@ -324,11 +395,16 @@ def mouse_hover_xy( x_coord, y_coord ):
 		#Display not open
 		return False
 
-
+## \brief Move the mouse by a given increment, and leave it there
+# \param x_inc The increment to move the mouse horizontally
+# \note A positive increment moves the mouse right, a negative increment moves the mouse left
+# \param y_inc The increment to move the mouse vertically
+# \note A positive increment moves the mouse down, a negative increment moves the mouse up
+# \param mouse_button The mouse button to click after moving
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_hover_rxy( x_inc, y_inc ):
-	"""Move the mouse to a location relative to where it currently is at"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse button hover relative xy: x=': + str(x_inc) + ' y=' + str(y_inc) )
-		out( 'Mouse button hover relative xy: x=': + str(x_inc) + ' y=' + str(y_inc) )
 		libcvautomation.xte_hoverMouseRXY( get_display(), x_inc, y_inc )
 
 		return True
@@ -336,16 +412,24 @@ def mouse_hover_rxy( x_inc, y_inc ):
 		#Display not open
 		return False
 
+## \brief Move the mouse to an image inside the root X11 window
+# \details For each image in \c image_names, search for it inside the root X11 window. Return once a match has been found, or the timeout value has been exceeded
+# \param image_names List of image names to search for
+# \param search_method The search method to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use the search methods.
+# \param tolerance The tolerance to use when finding each \c image. See \ref libcvautomation_search_methods for more information on how to use tolerance.
+# \param timeout Wait for \c timeout seconds before giving up the search for \c image_names in the root X11 window.
+# \note \c use_wait must be set to \c True for this parameter to have any effect
+# \param use_wait Set to \c True to make this function wait \c timeout seconds before giving up finding an image.
+# \note If set to \c False, this function will go through the list of \c image_names once before giving up.
+# \returns Return \c False if the X11 display was not opened before execution or no images were found, and \c True otherwise
 def mouse_hover_image( [image_names], search_method = _search_method_default,
 						tolerance = _tolerance_default, timeout = _timeout_default,
-						mouse_button = _mouse_button_default, use_wait = True,
+						use_wait = True, use_center = True ):
-						use_center = True ):
+	if _check_display():
-	"""Move the mouse to an image inside the root X11 window"""
+		_log_output( 'Mouse button click on image: Images=' + image_names + 
-	if check_display():
-		out( 'Mouse button click on image: Images=' + image_names + 
 				' search_method=' + search_method + ' tolerance=' + tolerance +
-				' timeout=' + _timeout_default + ' mouse_button=' +
+				' timeout=' + _timeout_default + ' use_wait=' + use_wait + 
-				' use_wait=' + use_wait + ' use_center=' + use_center)
+				' use_center=' + use_center)
 
 		if use_wait:
 			#Loop through all images 'timeout' times, and click on the first match
@@ -381,44 +465,53 @@ def mouse_hover_image( [image_names], search_method = _search_method_default,
 		#Display not open or no image found
 		return False
 
-
+## \brief Jiggle the mouse in place
+# \details Move the mouse right and down 1 pixel, and back. Useful for activating menu entries, etc.
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_jiggle():
 	"""Jiggle the mouse in place"""
-	if check_display():
+	if _check_display():
-		out( 'Mouse button jiggle' )
+		_log_output( 'Mouse button jiggle' )
 		libcvautomation.xte_mouseJiggle( get_display() )
 		return True
 	else:
 		#Display not open
 		return False
 
-
+## \brief Scroll the mouse wheel up
+# \details This is the same as pressing mouse button 4
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_scroll_up():
-	"""Scroll the mouse wheel up"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse scroll up' )
-		out( 'Mouse scroll up' )
 		libcvautomation.xte_mouseScrollUp( get_display() )
 		return True
 	else:
 		#Display not open
 		return False
 
+## \brief Scroll the mouse wheel down
+# \details This is the same as pressing mouse button 5
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def mouse_scroll_down():
-	"""Scroll the mouse wheel down"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Mouse scroll down' )
-		out( 'Mouse scroll down' )
 		libcvautomation.xte_mouseScrollDown( get_display() )
 		return True
 	else:
 		#Display not open
 		return False
 
-def mouse_drag_n_drop( drag_image, drag_to ):
+## \brief Drag and drop one image to another
-	"""Drag and drop from one location to another"""
+# \param drag_image The image to drag from
-	if check_display():
+# \param drag_to The image giving the location to drag to
-		out( 'Mouse drag and drop: dragging from=' + drag_image +
+# \param use_center Drag and drop the image using the center of the image as the location where the mouse will click and drag to
+# \returns Return \c False if the X11 display was not opened before execution or an image was not found, and \c True otherwise
+def mouse_drag_n_drop( drag_image, drag_to, use_center = True ):
+	if _check_display():
+		_log_output( 'Mouse drag and drop: dragging from=' + drag_image +
 			' dragging to=' + drag_to )
-		successful_hover = mouse_hover_image( drag_image )
+		successful_hover = mouse_hover_image( drag_image, use_center=use_center )
 		if successful_hover:
 			mouse_down( mouse_button=1 )
 			successful_hover = mouse_hover_image( drag_to )
@@ -430,54 +523,70 @@ def mouse_drag_n_drop( drag_image, drag_to ):
 		#Display not open
 		return False
 
-
+## \brief Enter a string of text on the keyboard
+# \details This function will simulate pressing the keys exactly as they are entered - unlike libcvautomation_funcs::key_down, libcvautomation_funcs::key_up, and libcvautomation_funcs::key_click, this function will display exactly what you entered: A string of \c '!' will produce a \c ! as a keypress.
+# \param string The string of text to enter on the keyboard
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def key_string( string ):
-	"""Enter a string of text on the keyboard"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Key string enter: string=' + string )
-		out( 'Key string enter: string=' + string )
 		libcvautomation.xte_clickKeyStr( get_display(), string )
 		return True
 	else:
 		#Display not open
 		return False
 
-
+## \brief Press a key down on the keyboard, and leave it down
+# \param key_name The name of the key to press down. Unlike libcvautomation_funcs::key_string, this command will press a single key corresponding to the string you give it - for example, \c 'a', \c 'b', or something fancy like \c 'space'.
+# \note See \ref xtest_key_strings for a full list of accepted key strings.
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def key_down( key_name ):
-	"""Press a key down on the keyboard"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Key button down: key_name=' + key_name )
-		out( 'Key button down: key_name=' + key_name )
 		libcvautomation.xte_keyDown( get_display(), key_name )
 		return True
 	else:
 		#Display not open
 		return False
 
+## \brief Release a key on the keyboard
+# \param key_name The name of the key to release. Unlike libcvautomation_funcs::key_string, this command will press a single key corresponding to the string you give it - for example, \c 'a', \c 'b', or something fancy like \c 'space'.
+# \note See \ref xtest_key_strings for a full list of accepted key strings.
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def key_up( key_name ):
-	"""Press a key down on the keyboard"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Key button up: key_name=' + key_name )
-		out( 'Key button up: key_name=' + key_name )
 		libcvautomation.xte_keyUp( get_display(), key_name )
 		return True
 	else:
 		#Display not open
 		return False
 
+## \brief Press and release a key on the keyboard
+# \param key_name The name of the key to click. Unlike libcvautomation_funcs::key_string, this command will press a single key corresponding to the string you give it - for example, \c 'a', \c 'b', or something fancy like \c 'space'.
+# \note See \ref xtest_key_strings for a full list of accepted key strings.
+# \returns Return \c False if the X11 display was not opened before execution, and \c True otherwise
 def key_click( key_name ):
-	"""Press a key down on the keyboard and release it"""
+	if _check_display():
-	if check_display():
+		_log_output( 'Key button click: key_name=' + key_name )
-		out( 'Key button click: key_name=' + key_name )
 		libcvautomation.xte_keyDown( get_display(), key_name )
 		return True
 	else:
 		#Display not open
 		return False
 
+## \brief Get the location of an image on the screen
+# \param image_names List of image names to search for in the root X11 window
+# \param search_method The search method to use when matching images. See \ref libcvautomation_search_methods for more information on using the \c search_method parameter
+# \param tolerance The tolerance to use when matching images. See \ref libcvautomation_search_methods for more informatino on using the \c tolerance parameter
+# \param use_center Set to \c True to return the center coordinate of an image. Set to \c False to use the top-left corner of an image
+# \warning Unlike libcvautomation_funcs::wait_for(), this method will not wait for an image to show up before looking for it.
+# \returns A dictionary pairing each image name with a cvaPoint class indicating the location it was found at (a point of (-1, -1) indicates the image was not found), or an empty dictionary if the X11 display was not opened before execution.
 def image_location( [image_names], search_method = _search_method_default,
 						tolerance = _tolerance_default,	use_center = True ):
-	"""Find the location of an image on screen (don't wait for it to show up)"""
+	if _check_display():
-	if check_display():
 		location_array = {}
-		out( 'Locate image (image_location): image_names=' + image_names )
+		_log_output( 'Locate image (image_location): image_names=' + image_names )
 		if use_center:
 			for image in image_names:
 				image_location = libcvautomation.matchSubImage_X11_center( get_display(), image,
@@ -494,15 +603,19 @@ def image_location( [image_names], search_method = _search_method_default,
 		#Display not open, but return the same type
 		return {}
 
-
+## \brief Get the location of an image on the screen, waiting for it to show up
-
+# \param image_names List of image names to search for in the root X11 window
+# \param search_method The search method to use when matching images. See \ref libcvautomation_search_methods for more information on using the \c search_method parameter
+# \param tolerance The tolerance to use when matching images. See \ref libcvautomation_search_methods for more informatino on using the \c tolerance parameter
+# \param timeout The time (in seconds) to wait when searching for an image on the root X11 window
+# \param use_center Set to \c True to return the center coordinate of an image. Set to \c False to use the top-left corner of an image
+# \returns A dictionary pairing each image name with a cvaPoint class indicating the location it was found at (a point of (-1, -1) indicates the image was not found), or an empty dictionary if the X11 display was not opened before execution.
 def wait_for( [image_names], search_method = _search_method_default,
 				tolerance = _tolerance_default, timeout = _timeout_default,
-				use_wait = True, use_center = True ):
+				use_center = True ):
-	"""Find the location of an image on screen (wait for it to show up if it's not immediately available)"""
+	if _check_display():
-	if check_display():
 		location_array = {}
-		out( 'Locate image (waitfor): image_names=' + image_names )
+		_log_output( 'Locate image (wait_for): image_names=' + image_names )
 		if use_center:
 			for image in image_names:
 				image_location = libcvautomation.waitForImage_location( get_display(), image,
@@ -519,9 +632,17 @@ def wait_for( [image_names], search_method = _search_method_default,
 		#Display not open, but return the same type
 		return {}
 
+## \brief Execute a libcvautomation command based on a string
+# \details This is a handler for the xte_commandString() function. 
+# \note Not all commands need all the parameters specified. See \ref xtest_command_strings for more information on how to use this function.
+# \param string The command string to execute
+# \param mouse_button The mouse button to click, if applicable
+# \param search_method The search method to use, if applicable. See \ref libcvautomation_search_methods for more information on how to use the \c search_method parameter
+# \param tolerance The tolerance to use, if applicable. See \ref libcvautomation_search_methods for more information on how to use the \c tolerance parameter
+# \param timeout The timeout (in seconds) to use, if applicable
+# \returns A cvaPoint class with the following points:<br>(0, 0) or up indicates a success.<br>(-1, -1) indicates either the command was not successful, or that the command was not recognized.<br>(-2, -2) indicates that the command did not need to return anything - For example, commands like \ref mousejiggle don't normally return a value.
 def command_string( string, mouse_button = _mouse_button_default, search_method = _search_method_default,
 					tolerance = _tolerance_default, timeout = _timeout_default)
-	"""Execute a libcvautomation command based on a string"""
 	#The return for this function bears a bit of talking about:
 	#	A return of (0, 0) or up is a success
 	#	A return of (-1, -1) is an error that either the command wasn't successful, or the command wasn't recognized
@@ -529,8 +650,8 @@ def command_string( string, mouse_button = _mouse_button_default, search_method
 	#		This helps differentiate between errors and functions like key_click that
 	#		don't really use a point
 
-	if check_display():
+	if _check_display():
-		out( 'Command string: string=' + string + ' search_method=' + str(search_method) +
+		_log_output( 'Command string: string=' + string + ' search_method=' + str(search_method) +
 				' tolerance=' + str(tolerance) + ' timeout=' + str(timeout) )
 		result_point = libcvautomation.xte_commandString( get_display(), string,
 							mouse_button, search_method,
@@ -539,8 +660,3 @@ def command_string( string, mouse_button = _mouse_button_default, search_method
 	else:
 		#Display not open, return an error point
 		return _libcvautomation_error_location
-
-## \file libcvautomation_funcs.py
-# \brief Libcvautomation wrapper for python
-# \details This source file is designed to give high-level access to libcvautomation using Python. It was modeled after the Bash wrapper, but allows for access to all the extra features of Python.
-# \author Bradlee Speice