Changeset 22214 in vbox for trunk/src/VBox/Main

Timestamp:

Aug 12, 2009 6:17:31 PM (15 years ago)

Author:

vboxsync

Message:

Main: documentation.

Location:

trunk/src/VBox/Main

Files:

• ConsoleImpl2.cpp (modified) (2 diffs)
• idl/VirtualBox.xidl (modified) (1 diff)
• xml/Settings.cpp (modified) (10 diffs)

trunk/src/VBox/Main/ConsoleImpl2.cpp

@@ -1914 +1914 @@
     if (FAILED(hrc = virtualBox->GetExtraDataKeys(ComSafeArrayAsOutParam(aGlobalExtraDataKeys))))
         AssertMsgFailed(("VirtualBox::GetExtraDataKeys failed with %Rrc\n", hrc));
+
+    // remember the no. of global values so we can call the correct method below
     size_t cGlobalValues = aGlobalExtraDataKeys.size();
+
     if (FAILED(hrc = pMachine->GetExtraDataKeys(ComSafeArrayAsOutParam(aMachineExtraDataKeys))))
         AssertMsgFailed(("IMachine::GetExtraDataKeys failed with %Rrc\n", hrc));
 
-    // build a combined list, prefix global keys with "G:"...
+    // build a combined list from global keys...
     std::list<Utf8Str> llExtraDataKeys;
     size_t i;
     for (i = 0; i < aGlobalExtraDataKeys.size(); ++i)
         llExtraDataKeys.push_back(Utf8Str(aGlobalExtraDataKeys[i]));
-    // ... and machine keys with "M:" (so we know below which method to call)
+    // ... and machine keys
     for (i = 0; i < aMachineExtraDataKeys.size(); ++i)
         llExtraDataKeys.push_back(Utf8Str(aMachineExtraDataKeys[i]));
+
     i = 0;
     for (std::list<Utf8Str>::const_iterator it = llExtraDataKeys.begin();
@@ -2813 +2817 @@
 }
 
-/* vi: set tabstop=4 shiftwidth=4 expandtab: */

trunk/src/VBox/Main/idl/VirtualBox.xidl

@@ -376 +376 @@
     </const>
     <const name="v1_5"     value="7">
-      <desc>Settings version "1.5", written by VirtualBox 2.1.x.</desc>
+      <desc>Legacy settings version, not currently supported.</desc>
       <!-- 2008-09-04: 2.0.0 released
            2008-11-20: settings version 1.5 introduced

trunk/src/VBox/Main/xml/Settings.cpp

@@ -272 +272 @@
 }
 
+/**
+ * Helper to create a string for a GUID.
+ * @param guid
+ * @return
+ */
 com::Utf8Str ConfigFileBase::makeString(const Guid &guid)
 {
@@ -398 +403 @@
 
 /**
+ * Creates an <ExtraData> node under the given parent element with
+ * <ExtraDataItem> childern according to the contents of the given
+ * map.
+ * This is in ConfigFileBase because it's used in both MainConfigFile
+ * MachineConfigFile, which both can have extradata.
  *
  * @param elmParent
@@ -423 +433 @@
 /**
  * Creates <DeviceFilter> nodes under the given parent element according to
- * the contents of the given USBDeviceFiltersList. If fHostMode is true,
- * this means that we're supposed to write filters for the IHost interface
- * (respect "action", omit "strRemote" and "ulMaskedInterfaces" in
- * struct USBDeviceFilter).
+ * the contents of the given USBDeviceFiltersList. This is in ConfigFileBase
+ * because it's used in both MainConfigFile (for host filters) and
+ * MachineConfigFile (for machine filters).
+ *
+ * If fHostMode is true, this means that we're supposed to write filters
+ * for the IHost interface (respect "action", omit "strRemote" and
+ * "ulMaskedInterfaces" in struct USBDeviceFilter).
+ *
  * @param elmParent
  * @param ll
@@ -681 +695 @@
  *
  * Throws variants of xml::Error for I/O, XML and logical content errors, which
- * the caller should catch; if this constructor does not throw, then the file has
- * been successfully read.
+ * the caller should catch; if this constructor does not throw, then the member
+ * variables contain meaningful values (either from the file or defaults).
  *
  * @param strFilename
@@ -767 +781 @@
 
 /**
- * Writes out a single <HardDisk> element for the given Medium structure
+ * Creates a single <HardDisk> element for the given Medium structure
  * and recurses to write the child hard disks underneath. Called from
  * MainConfigFile::write().
+ *
  * @param elmMedium
  * @param m
@@ -818 +833 @@
 
 /**
- * Called from the IMachine interface to write out a machine config file. This
+ * Called from the IVirtualBox interface to write out VirtualBox.xml. This
  * builds an XML DOM tree and writes it out to disk.
  */
@@ -921 +936 @@
 
 /**
+ * Called from MachineConfigFile::readHardware() to network information.
  * @param elmNetwork
  * @param ll
@@ -1484 +1500 @@
  * have their own storage controllers sections.
  *
- * This is only called for settings version 1.7 and above; see readHardDiskAttachments_pre1_7
+ * This is only called for settings version 1.7 and above; see readHardDiskAttachments_pre1_7()
  * for earlier versions.
  *
@@ -1645 +1661 @@
 
 /**
- * Called from the constructor to actually read in the Machine element
+ * Called from the constructor to actually read in the <Machine> element
  * of a machine config file.
  * @param elmMachine
@@ -1722 +1738 @@
  *
  * Throws variants of xml::Error for I/O, XML and logical content errors, which
- * the caller should catch; if this constructor does not throw, then the file has
- * been successfully read and parsed.
+ * the caller should catch; if this constructor does not throw, then the member
+ * variables contain meaningful values (either from the file or defaults).
  *
  * @param strFilename