Index: /trunk/src/VBox/Main/idl/VirtualBox.xidl
===================================================================
--- /trunk/src/VBox/Main/idl/VirtualBox.xidl	(revision 33766)
+++ /trunk/src/VBox/Main/idl/VirtualBox.xidl	(revision 33767)
@@ -1542,25 +1542,13 @@
         </ul>
 
-        See the <link to="IMachine::name"/> attribute description for more details about
-        the machine name.
-
-        Every machine has a <i>settings file</i> that is used to store
-        the machine configuration. This file is stored in a directory called the
-        <i>machine settings subfolder</i>. Both the settings subfolder and file
-        will have a name that corresponds to the name of the virtual machine.
-        You can specify where to create the machine setting subfolder using the
-        @a baseFolder argument.
+        See <link to="IMachine::name"/> and <link to="#createMachine"/> for more
+        details about the machine name.
 
         If @a baseFolder is a @c null or empty string (which is recommended), the
         default machine settings folder
         (see <link to="ISystemProperties::defaultMachineFolder" />) will be used as
-        a base folder for the created machine. Otherwise the given base folder
+        a base folder for the created machine, resulting in a file name like
+        "/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder
         will be used.
-
-        In either case, the full path to the resulting settings file has the
-        following structure:
-        <pre>
-          &lt;base_folder&gt;/&lt;machine_name&gt;/&lt;machine_name&gt;.xml
-        </pre>
 
         This method does not access the host disks. In particular, it does not check
@@ -1585,13 +1573,15 @@
         VirtualBox machine settings files use a custom XML dialect. Starting
         with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced,
-        and machine files can be created at arbitrary locations. However, it is
-        is recommended that machines are created in the "VirtualBox VMs" folder
-        created in the user's home directory
-        (e.g. "/home/user/VirtualBox VMs/name/name.vbox").
-
-        If you specify NULL for the @a settingsFile argument,
-        <link to="#composeMachineFilename" /> is called automatically to have
-        such a recommended name composed based on the machine name given in
-        the @a name argument.
+        and machine files can be created at arbitrary locations.
+
+        However, it is is recommended that machines be created in the default
+        machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see
+        <link to="ISystemProperties::defaultMachineFolder" />). If you specify
+        NULL for the @a settingsFile argument, <link to="#composeMachineFilename" />
+        is called automatically to have such a recommended name composed based
+        on the machine name given in the @a name argument.
+
+        If the resulting settings file already exists, this method will fail,
+        unless @a forceOverwrite is set.
 
         The new machine is created unregistered, with the initial configuration
@@ -1625,7 +1615,4 @@
         guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
         array.
-
-        If the resulting settings file already exists, this method will fail
-        with <link to="VBOX_E_FILE_ERROR"/>.
 
         Optionally, you may specify an UUID of to assign to the created machine.
@@ -3562,4 +3549,8 @@
         will return an appropriate error message explaining the exact
         reason and the changes you made to this machine will not be saved.
+
+        Starting with VirtualBox 4.0, a “.vbox” extension of the settings
+        file is recommended, but not enforced. (Previous versions always
+        used a generic ".xml" extension.)
       </desc>
     </attribute>