au3 0.1.1 → 0.1.2

data/lib/AutoItX3/filedir.rb

@@ -1,6 +1,6 @@
 #Encoding: UTF-8
 #This file is part of au3. 
-#Copyright © 2009 Marvin Gülker
+#Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
 #
 #au3 is published under the same terms as Ruby. 
 #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -9,15 +9,18 @@ module AutoItX3
   
   class << self
     
-    #====Arguments
+    #Maps a network drive.  
+    #===Parameters
     #Every | is ment to be a backslash. 
-    #- device: The device letter to map the drive to, in the form <tt>"X:"</tt>. If this is an asterisk *, the next available letter will be used. 
-    #- remote_share: The address of the network drive, in the form <tt>"||Server|Drive"</tt> or <tt>"||Server|Share"</tt>. 
-    #- flags (0): A combination (via +) of 1 (PersistantMapping) and 8 (Show authentification dialog if neccessary). 
-    #- username (""): The username, of the form <tt>"username"</tt> or <tt>"Domain|username"</tt>. 
-    #- password (""): The login password. 
-    #====Description
-    #Maps a network drive and raises an Au3Error if the action is not successful. 
+    #[+device+] The device letter to map the drive to, in the form <tt>"X:"</tt>. If this is an asterisk *, the next available letter will be used. 
+    #[+remote_share+] The address of the network drive, in the form <tt>"||Server|Drive"</tt> or <tt>"||Server|Share"</tt>. 
+    #[+flags+] (0) A combination (via +) of 1 (PersistantMapping) and 8 (Show authentification dialog if neccessary). 
+    #[+username+] ("") The username, of the form <tt>"username"</tt> or <tt>"Domain|username"</tt>. 
+    #[+password+] (""): The login password. 
+    #===Return value
+    #The assigned drive letter. 
+    #===Raises
+    #[Au3Error] Failed to connect the network drive. 
     def add_drive_map(device, remote_share, flags = 0, username = "", password = "")
       @functions[__method__] ||= AU3_Function.new("DriveMapAdd", 'SSLSSPI')
       buffer = " " * BUFFER_SIZE
@@ -35,21 +38,29 @@ module AutoItX3
       end
     end
     
-    #Disconnects a network drive. +device+ can be either of form <tt>"X:"</tt> or 
-    #<tt>"||Server|share"</tt> (imagine every | to be a backslash). 
-    #Raises an Au3Error if the disconnection was unsucsessful. 
+    #Disconnects a network drive. 
+    #===Parameters
+    #[+device+] The device to disconnect. Can be either of form <tt>"X:"</tt> or <tt>"||Server|share</tt> (| is a backslash). 
+    #===Return value
+    #nil. 
+    #===Raises
+    #[Au3Error] Couldn't disconnect the network drive. 
     def delete_drive_map(device)
       @functions[__method__] ||= AU3_Function.new("DriveMapDel", 'S', 'L')
       result = @functions[__method__].call(device)
       if result == 0
         raise(Au3Error, "Failed to remove remote device '#{device}'!")
       end
-      true
+      nil
     end
     
-    #Gets the server of the network drive named by +device+ or raises an Au3Error if it 
-    #can't access the device for some reason. The returned string will be of form 
-    #<tt>"||Server|drive"</tt> (every | is ment to be a backslash).  
+    #Gets the server of a network drive. 
+    #===Parameters
+    #[+device+] The device to check. 
+    #===Return value
+    #A string of form <tt>"||Server|drive"</tt>, where every | is meant to be a backslash. 
+    #===Raises
+    #[Au3Error] Couldn't retrieve the requested information. 
     def get_drive_map(device)
       @functions[__method__] ||= AU3_Function.new("DriveMapGet", 'SPI')
       buffer = " " * BUFFER_SIZE
@@ -63,6 +74,14 @@ module AutoItX3
     end
     
     #Deletes a key-value pair in a standard <tt>.ini</tt> file. 
+    #===Parameters
+    #[+filename+] The filename of the file. 
+    #[+section+] The section the key resides in. 
+    #[+key+] The key to delete. 
+    #===Return value
+    #true on success, otherwise false. 
+    #===Example
+    #  AutoItX3.delete_ini_entry("myini.ini", "mysection", "mykey")
     def delete_ini_entry(filename, section, key)
       @functions[__method__] ||= AU3_Function.new("IniDelete", 'SSS', 'L')
       if @functions[__method__].call(filename.wide, section.wide, key.wide) == 0
@@ -72,9 +91,23 @@ module AutoItX3
       end
     end
     
-    #Reads a value from a standard <tt>.ini</tt> file or returns the string given by +default+ 
-    #if it can't find the key. The returned string will have a maximum length of 99,999 characters. 
-    def read_ini_entry(filename, section, key, default = nil)
+    #Reads a value from a standard <tt>.ini</tt> file. 
+    #===Parameters
+    #[+filename+] The filename of the file. 
+    #[+section+] The section the key resides in. 
+    #[+key+] The key to read. 
+    #[+default+] ("")A string to return on failure. 
+    #===Return value
+    #The value of the +default+ parameter. 
+    #===Example
+    #  puts AutoItX3.read_ini_entry("myini.ini", "mysection", "mykey") #=> myvalue
+    #  #Nonexistant key: 
+    #  puts AutoItX3.read_ini_entry("myini.ini", "mysection", "mynonexsistingkey") #=> 
+    #  #With default value
+    #  puts AutoItX3.read_ini_entry("myini,ini", "mysection", "mynonexsistingkey", "NOTHING") #=> NOTHING
+    #===Remarks
+    #The returned string has a maximum length of <tt>AutoItX3::BUFFER_SIZE - 1 </tt> characters. 
+    def read_ini_entry(filename, section, key, default = "")
       @functions[__method__] ||= AU3_Function.new("IniRead", 'SSSSPI')
       buffer = " " * BUFFER_SIZE
       buffer.wide!
@@ -82,8 +115,22 @@ module AutoItX3
       buffer.normal.strip
     end
     
-    #Writes the specified key-value pair in a <tt>.ini</tt> file. Existing key-value pairs are overwritten. 
-    #A non-existing file will be created. Raises an Au3Error if +filename+ is read-only. 
+    #Writes the specified key-value pair in a <tt>.ini</tt> file. 
+    #===Parameters
+    #[+filename+] The file's filename. 
+    #[+section+] The section you want to write in. 
+    #[+key+] The key whose value you want to write. 
+    #[+value+] The value to write. 
+    #===Return value
+    #The +value+ argument. 
+    #===Raises
+    #[Au3Error] +filename+ is read-only. 
+    #===Example
+    #  AutoItX3.write_ini_entry("minini.ini", "mysection", "mykey", "myvalue")
+    #===Remarks
+    #Both the +section+ and the +key+ will be created if they aren't there already. Likewise is the file if nonexistant. 
+    #
+    #If the specified key-value pair already exists, it will be overwritten. 
     def write_ini_entry(filename, section, key_value, value)
       @functions[__method__] ||= AU3_Function.new("IniWrite", 'SSSS', 'L')
       

data/lib/AutoItX3/graphic.rb

@@ -1,6 +1,6 @@
 #Encoding: UTF-8
 #This file is part of au3. 
-#Copyright © 2009 Marvin Gülker
+#Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
 #
 #au3 is published under the same terms as Ruby. 
 #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -9,8 +9,22 @@ module AutoItX3
   
   class << self
     
-    #Computes a checksum of the pixels in the specified region. If the checksum 
-    #changes, that only indidcates that *something* has changed, not *what*. 
+    #Computes a checksum of the pixels in the specified region. 
+    #===Parameters
+    #[+x1+] Upper-left X-Coordinate of the region. 
+    #[+y1+] Upper-left Y-Coordinate of the region. 
+    #[+x2+] Lower-right X-Coordinate of the region. 
+    #[+y2+] Lower-right Y-Coordinate of the region. 
+    #[+step+] (1) Indicatates how many pixels are used for the computation. Every <tt>step</tt>-th pixel will be checked. 
+    #===Return value
+    #The computed checksum. 
+    #===Example
+    #  #Compute the checksum of [0, 0, 100, 100]
+    #  p AutoItX3.pixel_checksum(0, 0, 100, 100) #=> 2252979179
+    #  #Then move a window into this region. 
+    #  p AutoItX3.pixel_checksum(0, 0, 100, 100) #=> 4287194203
+    #===Remarks
+    #If the checksum changes, that only indidcates that *something* has changed, not *what*. 
     #Note that this method may be very time-consuming, so think about increasing the 
     #+step+ parameter (but bear in mind that that will generate more inaccurate checksums). 
     def pixel_checksum(x1, y1, x2, y2, step = 1)
@@ -18,8 +32,18 @@ module AutoItX3
       @functions[__method__].call(x1, y1, x2, y2, step)
     end
     
-    #Retrieves the *decimal* color value of a pixel. If you want the hexadecimal, 
-    #pass in true as a third parameter. 
+    #Retrieves the color value of the pixel at the specified position. 
+    #===Parameters
+    #[+x+] The pixel's X coordinate. 
+    #[+y+] The pixel's Y coordinate. 
+    #[+hex+] Changes the return value, see below. 
+    #===Return value
+    #The decimal color value of the specified pixel. If you set +hex+ to true, 
+    #you get a string in form <tt>#RRGGBB</tt> that describes the color in 
+    #hexadecimal format. 
+    #===Example
+    #  p AutoItX3.get_pixel_color(15, 15) #=> 1057590
+    #  p AutoItX3.get_pixel_color(15, 15, true) #=> "#102336"
     def get_pixel_color(x, y, hex = false)
       @functions[__method__] ||= AU3_Function.new("PixelGetColor", 'LL', 'L')
       res = @functions[__method__].call(x, y)

data/lib/AutoItX3/keyboard.rb

@@ -1,6 +1,6 @@
 #Encoding: UTF-8
 #This file is part of au3. 
-#Copyright © 2009 Marvin Gülker
+#Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
 #
 #au3 is published under the same terms as Ruby. 
 #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -9,9 +9,23 @@ module AutoItX3
   
   class << self
     
-    #Simulates the given keystrokes. If you don't 
-    #set +flag+ to true (which disables escape sequences), you may 
-    #use some of the follwing escape sequences in braces { and } 
+    #Simulates keyboard input. 
+    #===Parameters
+    #[+keys+] The keystrokes to simulate. See _Remarks_. 
+    #[+flag+] (+false+) If set to +true+, escape sequences in braces { and } are ignored. 
+    #===Return value
+    #nil. 
+    #===Example
+    #  #Simulate [SHIFT] + [A], [B] and [C]. 
+    #  AutoItX3.send_keys("Abc")
+    #  #Simulate [A], [ESC] and b. 
+    #  AutoItX3.send_keys("a{ESC}b")
+    #  #Ignore the escape sequence and send it as regular keystrokes. 
+    #  AutoItX3.send_keys("a{ESC}b", true)
+    #  #Sends [ALT] + [F]
+    #  AutoItX3.send_keys("!F")
+    #===Remarks
+    #You may use some of the follwing escape sequences in braces { and } 
     #(copied from the AutoItX3 help): 
     #  Escape sequence     | Resulting keypress
     #  ====================+============================================================

data/lib/AutoItX3/misc.rb

@@ -1,6 +1,6 @@
 #Encoding: UTF-8
 #This file is part of au3. 
-#Copyright © 2009 Marvin Gülker
+#Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
 #
 #au3 is published under the same terms as Ruby. 
 #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -9,9 +9,20 @@ module AutoItX3
   
   class << self
     
-    #Blocks user input or enables it (but the user can gain back control by 
-    #pressing [CTRL] + [ALT] + [DEL]). In older versions of Windows, 
-    #AutoIt may also be blocked. Does not work with Windows Vista. 
+    #Blocks user input. 
+    #===Parameters
+    #[+val+] Wheather the user input should be blocked or not. 
+    #===Return value
+    #The passed argument, double-negated to ensure a boolean value. 
+    #===Example
+    #  p AutoItX3.input_blocked? #=> false
+    #  AutoItX3.block_input = true
+    #  p AutoItX3.input_blocked? #=> true
+    #  AutoItX3.block_input = false
+    #  p AutoItX3.input_blocked? #=> false
+    #===Remarks
+    #The user can gain back control by pressing [CTRL] + [ALT] + [DEL]. 
+    #In older versions of Windows AutoIt itself may also be blocked. 
     def block_input=(val)
       @functions[__method__] ||= AU3_Function.new("BlockInput", 'L')
       @functions[__method__].call(!!val)
@@ -19,45 +30,72 @@ module AutoItX3
     end
     
     #Returns wheather or not input is blocked by AutoItX3. 
+    #===Return value
+    #true or false. 
+    #===Example
+    #  #See #block_input. 
+    #===Remarks
+    #This method fails to report that input has been enabled again if the 
+    #user has pressed [CTRL] + [ALT] + [DEL] after a call to #block_input=. 
     def input_blocked?
       @input_blocked ||= false
     end
     
-    #Opens the cd drive named in +drive+. +drive+ should be of form 
-    #<tt>"X:"</tt>. The cd tray must be local at this computer, remote drives 
+    #Opens a CD/DVD drive. 
+    #===Parameters
+    #[+tray+] The drive to eject, a string of form <tt>"X:"</tt>. 
+    #===Return value
+    #true on success, false otherwise. 
+    #===Example
+    #  AutoItX3.open_cd_tray("E:") #| true
+    #  AutoItX3.open_cd_tray("Y:") #| false
+    #===Remarks
+    #The cd tray must be local at this computer, remote drives 
     #cannot be accessed. 
     def open_cd_tray(tray)
       @functions[__method__] ||= AU3_Function.new("CDTray", 'SS', 'L')
       raise(ArgumentError, "The drive name has to be of form 'X:'!") unless tray =~ /^\w:$/
-      if @functions[__method__].call(tray.wide, "open".wide) == 0
-        return false
-      else
-        return true
-      end
+      @functions[__method__].call(tray.wide, "open".wide) == 1
     end
     
-    #Closes a cd tray. +drive+ should be of form <tt>"X:"</tt>. The cd tray must 
-    #be local at this computer, remote drives cannot be accessed. 
-    #The method may return true if +drive+ is a laptop drive which can only be 
+    #Closes a CD/DVD drive. 
+    #===Parameters
+    #[+tray+] The drive to close. 
+    #===Return value
+    #true on success, false otherwise. 
+    #===Example
+    #  AutoItX3.open_cd_tray("E:")
+    #  AutoItX3.close_cd_tray("E:")
+    #===Remarks
+    #The cd tray must be local at this computer, remote drives 
+    #cannot be accessed. 
+    #This method may return true if +drive+ is a laptop drive which can only be 
     #closed manually. 
     def close_cd_tray(tray)
       @functions[__method__] ||= AU3_Function.new("CDTray", 'SS', 'L')
       raise(ArgumentError, "The drive name has to be of form 'X:'!") unless tray =~ /^\w:$/
-      if @functions[__method__].call(tray.wide, "closed".wide) == 0
-        return false
-      else
-        return true
-      end
+      @functions[__method__].call(tray.wide, "closed".wide) == 1
     end
     
     #Determines wheather the current user has administrator privileges. 
+    #===Return value
+    #true or false, 
+    #===Example
+    #  p AutoItX3.is_admin? #=> false
     def is_admin?
       @functions[__method__] ||= AU3_Function.new("IsAdmin", 'V', 'L')
-      return false if @functions[__method__].call == 0
-      true
+      @functions[__method__].call == 1
     end
     
     #Writes +text+ to the Windows clipboard. 
+    #===Parameters
+    #[+text+] The text to write. 
+    #===Return value
+    #The argument passed. 
+    #===Example
+    #  AutoItX3.cliptext = "I love Ruby!"
+    #  puts AutoItX3.cliptext #=> I love Ruby!
+    #===Remarks
     #You can't write NUL characters to the clipboard, the text will 
     #be terminated. 
     def cliptext=(text)
@@ -66,8 +104,16 @@ module AutoItX3
       text
     end
     
-    #Returns the text saved in the clipboard. It will be truncated at the 99,999th character or 
-    #at a NUL char. 
+    #Reads the Windows clipboard. 
+    #===Return value
+    #The text saved in the clipboard, encoded in UTF-8. 
+    #===Example
+    #  puts AutoItX3.cliptext #=> I love Ruby!
+    #===Remarks
+    #Returns the text saved in the clipboard. It will be truncated at the 
+    #<tt>AutoItX3::BUFFER_SIZE - 1</tt>th character or at a NUL character. 
+    #
+    #If the clipboard doesn't contain text, this method returns an empty string. 
     def cliptext
       @functions[__method__] ||= AU3_Function.new("ClipGet", 'PL')
       cliptext = " " * BUFFER_SIZE
@@ -80,9 +126,16 @@ module AutoItX3
     #  tool_tip( text [, x = INTDEFAULT [, y = INTDEFAULT ] ] ) ==> nil
     #  tooltip( text [, x = INTDEFAULT [, y = INTDEFAULT ] ] ) ==> nil
     #
-    #Displays a tooltip at the given position. If +x+ and +y+ are ommited, 
-    #the tooltip will be displayed at the current cursor position. Coordinates 
-    #out of range are automatically corrected. 
+    #Displays a tooltip at the given position. 
+    #===Parameters
+    #[+text+] The text to display. 
+    #[+x+] (+INTDEFAULT+) The X coordinate where to display the tooltip. Defaults to the cursor's X coordinate if ommited. 
+    #[+y+] (+INTDEFAULT+) The Y coordinate where to display the tooltip. Defaults to the cursor's Y coordinate if ommited. 
+    #===Return value
+    #nil. 
+    #===Remarks
+    #Coordinates out of range are automatically corrected. 
+    #
     #The tooltip will be deleted when the program ends, or after a system-dependent 
     #timeout. 
     def tool_tip(text, x = INTDEFAULT, y = INTDEFAULT)
@@ -91,8 +144,12 @@ module AutoItX3
     end
     alias tooltip tool_tip
     
-    #Wait for the specified amount of milliseconds. In AutoIt, this function is named 
-    #"Sleep", but to avoid compatibility issues with Ruby's own sleep I decided to 
+    #Wait for the specified amount of milliseconds. 
+    #===Return value
+    #nil. 
+    #===Remarks
+    #In AutoIt, this function is named "Sleep", but to avoid compatibility 
+    #issues with Ruby's own sleep I decided to 
     #name the function "msleep" (the "m" indicates "milli"). If you wish to name it 
     #"sleep", simply define an alias. 
     def msleep(msecs)

data/lib/AutoItX3/mouse.rb

@@ -1,6 +1,6 @@
 #Encoding: UTF-8
 #This file is part of au3. 
-#Copyright © 2009 Marvin Gülker
+#Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
 #
 #au3 is published under the same terms as Ruby. 
 #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -34,13 +34,24 @@ module AutoItX3
   
   class << self
     
-    #====Arguments
-    #- x (INTDEFAULT): The X position. The cursor's current X if not specified. 
-    #- y (INTDEFAULT): The Y position. The cursor's current Y if not specified. 
-    #- button("Primary"): The mouse button to click width. On a mouse for left-handed people the right, for right-handed people the left mouse button. 
-    #- clicks(1): The number of times to click. 
-    #- speed(10): The speed the mouse cursor will move with. If set to 0, the cursor is set immediatly. 
-    #
+    #Executes a mouse click. 
+    #===Parameters
+    #* x (INTDEFAULT): The X position. The cursor's current X if not specified. 
+    #* y (INTDEFAULT): The Y position. The cursor's current Y if not specified. 
+    #* button(<tt>"Primary"</tt>): The mouse button to click width. On a mouse for left-handed people the right, for right-handed people the left mouse button. 
+    #* clicks(1): The number of times to click. 
+    #* speed(10): The speed the mouse cursor will move with. If set to 0, the cursor is set immediatly. 
+    #===Return value
+    #nil. 
+    #===Raises
+    #[Au3Error] Invalid mouse button specified. 
+    #===Example
+    #  #Normal mouse click at (100|100). 
+    #  AutoItX3.mouse_click(100, 100)
+    #  #Click with the right (or left if buttons are swapped) button
+    #  AutoItX3.mouse_click(AutoItX3::INTDEFAULT, AutoItX3::INTDEFAULT, "Secondary")
+    #  #Don't move the cursor
+    #  AutoItX3.mouse_click(100, 100, "Primary", 1, 0)
     #Clicks the mouse. 
     def mouse_click(x = INTDEFAULT, y = INTDEFAULT, button = "Primary", clicks = 1, speed = 10)
       @functions[__method__] ||= AU3_Function.new("MouseClick", 'SLLLL', 'L')
@@ -50,7 +61,22 @@ module AutoItX3
       nil
     end
     
-    #Performes a drag & drop operation with the given parameters. 
+    #Performes a drag & drop operation. 
+    #===Parameters
+    #[+x1+] The start X coordinate. 
+    #[+y1+] The start Y coordinate. 
+    #[+x2+] The goal X coordinate. 
+    #[+y2+] The goal Y coordinate. 
+    #[+button+] The button to hold down while moving. 
+    #[+speed+] The cursor's speed. If 0, the cursor is set directly to the goal position. 
+    #===Return value
+    #nil. 
+    #===Raises
+    #[Au3Error] Invalid mouse button specified. 
+    #===Example
+    #  AutoItX3.drag_mouse(10, 10, 73, 86)
+    #  #With the secondary mouse button
+    #  AutoItX3.drag_mouse(10, 10, 73, 86, "Secondary")
     def drag_mouse(x1, y1, x2, y2, button = "Primary", speed = 10)
       @functions[__method__] ||= AU3_Function.new("MouseClickDrag", 'SLLLLL', 'L')
       @functions[__method__].call(button.wide, x1, y1, x2, y2, speed)
@@ -63,7 +89,15 @@ module AutoItX3
     #  hold_mouse_down( [ button = "Primary" ] ) ==> nil
     #  mouse_down( [ button = "Primary" ] ) ==> nil
     #
-    #Holds a mouse button down (the left by default, or the right if mouse buttons are swapped). 
+    #Holds a mouse button down. 
+    #===Parameters
+    #[+button+] (<tt>"Primary"</tt>) The button to hold down. 
+    #===Return value
+    #nil. 
+    #===Example
+    #  AutoItX3.hold_mouse_down("Primary")
+    #  AutoItX3.hold_mouse_down("Secondary")
+    #===Remarks
     #You should release the mouse button somewhen. 
     def hold_mouse_down(button = "Primary")
       @functions[__method__] ||= AU3_Function.new("MouseDown", 'S')
@@ -75,7 +109,11 @@ module AutoItX3
     #  cursor_id ==> aFixnum
     #  get_cursor_id ==> aFixnum
     #
-    #Returns one of the *_CURSOR constants to indicate which cursor icon is actually shown. 
+    #Get the cursor that is shown at the moment. 
+    #===Return value
+    #One of the *_CURSOR constants to indicate which cursor icon is actually shown. 
+    #===Example
+    #  p AutoItX3.cursor_id #=> 5 #IBEAM_CURSOR, that one with the >I< form for editing texts. 
     def cursor_id
       @functions[__method__] ||= AU3_Function.new("MouseGetCursor", '', 'L')
       @functions[__method__].call
@@ -85,7 +123,11 @@ module AutoItX3
     #  cursor_pos ==> anArray
     #  get_cursor_pos ==> anArray
     #
-    #Returns the current cursor position in a two-element array of form <tt>[x, y]</tt>. 
+    #Returns the current cursor position. 
+    #===Return value
+    #The current cursor position in a two-element array of form <tt>[x, y]</tt>. 
+    #===Example
+    #  p AutoItX3.cursor_pos #=> [127, 345]
     def cursor_pos
       @functions[:cursor_pos_x] ||= AU3_Function.new("MouseGetPosX", 'V', 'L')
       @functions[:cursor_pos_y] ||= AU3_Function.new("MouseGetPosY", 'V', 'L')
@@ -96,8 +138,13 @@ module AutoItX3
     #  move_mouse( x , y [, speed = 10 ] ) ==> nil
     #  mouse_move( x , y [, speed = 10 ] ) ==> nil
     #
-    #Moves the mouse cursor to the given position. If +speed+ is 0, 
-    #it's set immediately. 
+    #Moves the mouse cursor to the given position. 
+    #===Parameters
+    #[+x+] The goal X coordinate. 
+    #[+y+] The goal Y coordinate. 
+    #[+speed+] (+10+) The speed to move the cursor with. 0 means no movement and the cursor is set directly to the goal position. 
+    #===Return value
+    #nil. 
     def move_mouse(x, y, speed = 10)
       @functions[__method__] ||= AU3_Function.new("MouseMove", 'LLL', 'L')
       @functions[__method__].call(x, y, speed)
@@ -109,14 +156,33 @@ module AutoItX3
     #  mouse_up( [ button = "Primary" ] ) ==> nil
     #
     #Releases a mouse button hold down by #hold_mouse_down. 
+    #===Parameters
+    #[+button+] (<tt>"Primary"</tt>) The mouse button to release. 
+    #===Return value
+    #nil. 
+    #===Example
+    #  AutoItX3.hold_mouse_down
+    #  AutoItX3.release_mouse
+    #  #With the secondary button
+    #  AutoItX3.hold_mouse_down("Secondary")
+    #  AutoItX3.release_mouse("Secondary")
     def release_mouse(button = "Primary")
       @functions[__method__] ||= AU3_Function.new("MouseUp", 'S')
       @functions[__method__].call(button.wide)
       nil
     end
     
-    #Scrolls up or down the mouse wheel +times+ times. Use 
-    #ether "Up" or "Down" as the value for +direction+. 
+    #Scrolls up or down the mouse wheel. 
+    #===Parameters
+    #[+direction+] The scrolling direction, either <tt>"up</tt> or <tt>"down</tt>. 
+    #[+times+] The scrolling steps. These <b>are not</b> full wheel turns. 
+    #===Return value
+    #nil. 
+    #===Example
+    #  #5 steps up. 
+    #  AutoItX3.mouse_wheel("up")
+    #  #3 steps down. 
+    #  AutoItX3.mouse_wheel("down", 3)
     def mouse_wheel(direction, times = 5)
       @functions[__method__] ||= AU3_Function.new("MouseWheel", 'SL')
       @functions[__method__].call(direction.wide, times)