Changeset 65120 in vbox for trunk/src/VBox/Main/src-server

Timestamp:

Jan 4, 2017 5:10:35 PM (8 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

112623

Message:

Main: doxygen fixes

Location:

trunk/src/VBox/Main/src-server

Files:

• ApplianceImplExport.cpp (modified) (2 diffs)
• ApplianceImplImport.cpp (modified) (2 diffs)
• BandwidthGroupImpl.cpp (modified) (1 diff)
• GuestOSTypeImpl.cpp (modified) (1 diff)
• HostImpl.cpp (modified) (15 diffs)
• HostNetworkInterfaceImpl.cpp (modified) (2 diffs)
• HostUSBDeviceImpl.cpp (modified) (2 diffs)
• MachineImpl.cpp (modified) (19 diffs)
• MediumAttachmentImpl.cpp (modified) (1 diff)
• MediumImpl.cpp (modified) (7 diffs)
• USBDeviceFilterImpl.cpp (modified) (3 diffs)
• linux/HostHardwareLinux.cpp (modified) (1 diff)

trunk/src/VBox/Main/src-server/ApplianceImplExport.cpp

@@ -53 +53 @@
 /**
 * Public method implementation.
-* @param appliance
+* @param aAppliance     Appliance object.
+* @param aLocation      Where to store the appliance.
+* @param aDescription   Appliance description.
 * @return
 */
@@ -618 +620 @@
 /**
  * Public method implementation.
- * @param format
- * @param options
- * @param path
- * @param aProgress
+ * @param aFormat   Appliance format.
+ * @param aOptions  Export options.
+ * @param aPath     Path to write the appliance to.
+ * @param aProgress Progress object.
  * @return
  */

trunk/src/VBox/Main/src-server/ApplianceImplImport.cpp

@@ -68 +68 @@
  * Thread implementation is in Appliance::readImpl().
  *
- * @param aFile
+ * @param aFile     File to read the appliance from.
+ * @param aProgress Progress object.
  * @return
  */
@@ -752 +753 @@
  * VirtualSystemScription instances created by Appliance::Interpret().
  * Thread implementation is in Appliance::i_importImpl().
- * @param aProgress
+ * @param aOptions  Import options.
+ * @param aProgress Progress object.
  * @return
  */

trunk/src/VBox/Main/src-server/BandwidthGroupImpl.cpp

@@ -90 +90 @@
 
 /**
- *  Initializes the object given another object
- *  (a kind of copy constructor). This object shares data with
- *  the object passed as an argument.
- *
- *  @param  aReshare
- *      When false, the original object will remain a data owner.
- *      Otherwise, data ownership will be transferred from the original
- *      object to this one.
- *
- *  @note This object must be destroyed before the original object
- *  it shares data with is destroyed.
- *
- *  @note Locks @a aThat object for writing if @a aReshare is @c true, or for
- *  reading if @a aReshare is false.
+ * Initializes the object given another object
+ * (a kind of copy constructor). This object shares data with
+ * the object passed as an argument.
+ *
+ * @param   aParent  Pointer to our parent object.
+ * @param   aThat
+ * @param   aReshare
+ *     When false, the original object will remain a data owner.
+ *     Otherwise, data ownership will be transferred from the original
+ *     object to this one.
+ *
+ * @note This object must be destroyed before the original object
+ * it shares data with is destroyed.
+ *
+ * @note Locks @a aThat object for writing if @a aReshare is @c true, or for
+ * reading if @a aReshare is false.
  */
 HRESULT BandwidthGroup::init(BandwidthControl *aParent,

trunk/src/VBox/Main/src-server/GuestOSTypeImpl.cpp

@@ -65 +65 @@
  *
  * @returns COM result indicator
- * @param aFamilyId          os family short name string
- * @param aFamilyDescription os family name string
- * @param aId                os short name string
- * @param aDescription       os name string
- * @param aOSType            global OS type ID
- * @param aOSHint            os configuration hint
- * @param aRAMSize           recommended RAM size in megabytes
- * @param aVRAMSize          recommended video memory size in megabytes
- * @param aHDDSize           recommended HDD size in bytes
+ * @param ostype containing the following parts:
+ * @a aFamilyId          os family short name string
+ * @a aFamilyDescription os family name string
+ * @a aId                os short name string
+ * @a aDescription       os name string
+ * @a aOSType            global OS type ID
+ * @a aOSHint            os configuration hint
+ * @a aRAMSize           recommended RAM size in megabytes
+ * @a aVRAMSize          recommended video memory size in megabytes
+ * @a aHDDSize           recommended HDD size in bytes
  */
-HRESULT GuestOSType::init(const Global::OSType &ostype)/*const char *aFamilyId, const char *aFamilyDescription,
-                          const char *aId, const char *aDescription,
-                          VBOXOSTYPE aOSType, uint32_t aOSHint,
-                          uint32_t aRAMSize, uint32_t aVRAMSize, uint64_t aHDDSize,
-                          NetworkAdapterType_T aNetworkAdapterType,
-                          uint32_t aNumSerialEnabled,
-                          StorageControllerType_T aDVDStorageControllerType,
-                          StorageBus_T aDVDStorageBusType,
-                          StorageControllerType_T aHDStorageControllerType,
-                          StorageBus_T aHDStorageBusType,
-                          ChipsetType_T aChipsetType
-                          AudioControllerType_T aAudioControllerType*/
-{
-#if 0
-    LogFlowThisFunc(("aFamilyId='%s', aFamilyDescription='%s', "
-                      "aId='%s', aDescription='%s', "
-                      "aType=%d, aOSHint=%x, "
-                      "aRAMSize=%d, aVRAMSize=%d, aHDDSize=%lld, "
-                      "aNetworkAdapterType=%d, aNumSerialEnabled=%d, "
-                      "aStorageControllerType=%d\n",
-                      aFamilyId, aFamilyDescription,
-                      aId, aDescription,
-                      aOSType, aOSHint,
-                      aRAMSize, aVRAMSize, aHDDSize,
-                      aNetworkAdapterType,
-                      aNumSerialEnabled,
-                      aStorageControllerType));
-#endif
-
+HRESULT GuestOSType::init(const Global::OSType &ostype)
+{
     ComAssertRet(ostype.familyId && ostype.familyDescription && ostype.id && ostype.description, E_INVALIDARG);
 

trunk/src/VBox/Main/src-server/HostImpl.cpp

@@ -537 +537 @@
  *
  * @returns COM status code
- * @param drives address of result pointer
+ * @param aDVDDrives    address of result pointer
  */
 
@@ -561 +561 @@
  *
  * @returns COM status code
- * @param drives address of result pointer
+ * @param   aFloppyDrives   address of result pointer
  */
 HRESULT Host::getFloppyDrives(std::vector<ComPtr<IMedium> > &aFloppyDrives)
@@ -628 +628 @@
  *
  * @returns COM status code
- * @param drives address of result pointer
+ * @param   aNetworkInterfaces  address of result pointer
  */
 HRESULT Host::getNetworkInterfaces(std::vector<ComPtr<IHostNetworkInterface> > &aNetworkInterfaces)
@@ -900 +900 @@
  *
  * @returns COM status code
- * @param   count address of result variable
+ * @param   aCount  address of result variable
  */
 
@@ -915 +915 @@
  *
  * @returns COM status code
- * @param   count address of result variable
+ * @param   aCount  address of result variable
  */
 HRESULT Host::getProcessorOnlineCount(ULONG *aCount)
@@ -929 +929 @@
  *
  * @returns COM status code
- * @param   count address of result variable
+ * @param   aCount  address of result variable
  */
 HRESULT Host::getProcessorCoreCount(ULONG *aCount)
@@ -943 +943 @@
  *
  * @returns COM status code
- * @param   count address of result variable
+ * @param   aCount  address of result variable
  */
 HRESULT Host::getProcessorOnlineCoreCount(ULONG *aCount)
@@ -957 +957 @@
  *
  * @returns COM status code
- * @param   cpu id to get info for.
- * @param   speed address of result variable, speed is 0 if unknown or aCpuId is invalid.
+ * @param   aCpuId  id to get info for.
+ * @param   aSpeed  address of result variable, speed is 0 if unknown or aCpuId
+ *          is invalid.
  */
 HRESULT Host::getProcessorSpeed(ULONG aCpuId,
@@ -973 +974 @@
  *
  * @returns COM status code
- * @param   cpu id to get info for.
- * @param   description address of result variable, empty string if not known or aCpuId is invalid.
+ * @param   aCpuId  id to get info for.
+ * @param   aDescription address of result variable, empty string if not known
+ *          or aCpuId is invalid.
  */
 HRESULT Host::getProcessorDescription(ULONG aCpuId, com::Utf8Str &aDescription)
@@ -995 +997 @@
  *
  * @returns COM status code
- * @param   Feature to query.
- * @param   address of supported bool result variable
+ * @param   aFeature    to query.
+ * @param   aSupported  supported bool result variable
  */
 HRESULT Host::getProcessorFeature(ProcessorFeature_T aFeature, BOOL *aSupported)
@@ -1118 +1120 @@
  *
  * @returns COM status code
- * @param   size address of result variable
+ * @param   aSize   address of result variable
  */
 HRESULT Host::getMemorySize(ULONG *aSize)
@@ -1136 +1138 @@
  *
  * @returns COM status code
- * @param   available address of result variable
+ * @param   aAvailable  address of result variable
  */
 HRESULT Host::getMemoryAvailable(ULONG *aAvailable)
@@ -1172 +1174 @@
  *
  * @returns COM status code
- * @param   os address of result variable
+ * @param   aVersion    address of result variable
  */
 HRESULT Host::getOSVersion(com::Utf8Str &aVersion)
@@ -1207 +1209 @@
  *
  * @returns COM status code
- * @param   time address of result variable
+ * @param   aUTCTime    address of result variable
  */
 HRESULT Host::getUTCTime(LONG64 *aUTCTime)
@@ -2049 +2051 @@
 /**
  * Called from getDrives() to build the DVD drives list.
- * @param pll
+ * @param   list    Media list
  * @return
  */

trunk/src/VBox/Main/src-server/HostNetworkInterfaceImpl.cpp

@@ -65 +65 @@
  * @returns COM result indicator
  * @param   aInterfaceName name of the network interface
- * @param   aGuid GUID of the host network interface
- * @param   ifType interface type
+ * @param   aShortName  short name of the network interface
+ * @param   aGuid       GUID of the host network interface
+ * @param   ifType      interface type
  */
 HRESULT HostNetworkInterface::init(Bstr aInterfaceName, Bstr aShortName, Guid aGuid, HostNetworkInterfaceType_T ifType)
@@ -274 +275 @@
  *
  * @returns COM status code
- * @param   aGuid GUI Id
- */
-HRESULT HostNetworkInterface::getId(com::Guid &aGuiId)
-{
-    aGuiId = mGuid;
+ * @param   aGuid GUID
+ */
+HRESULT HostNetworkInterface::getId(com::Guid &aGuid)
+{
+    aGuid = mGuid;
 
     return S_OK;

trunk/src/VBox/Main/src-server/HostUSBDeviceImpl.cpp

@@ -509 +509 @@
  *
  * @param   aMachine        Machine this device should be attach to.
+ * @param   aCaptureFilename Filename to capture the USB traffic to.
  * @param   aMaskedIfs      The interfaces to hide from the guest.
  */
@@ -2231 +2232 @@
 
  * @param   aNewState       The new state (transitional).
- * @param   aFinalSubState  The final state of the transition (non-transitional).
+ * @param   aFinalState     The final state of the transition (non-transitional).
  * @param   aNewSubState    The new sub-state when applicable.
  *

trunk/src/VBox/Main/src-server/MachineImpl.cpp

@@ -286 +286 @@
  *  @param aId          UUID for the new machine.
  *  @param fForceOverwrite Whether to overwrite an existing machine settings file.
+ *  @param fDirectoryIncludesUUID Whether the use a special VM directory naming
+ *                      scheme (includes the UUID).
  *
  *  @return  Success indicator. if not S_OK, the machine object is invalid
@@ -407 +409 @@
  *
  *  @param aParent      Associated parent object
- *  @param aConfigFile  Local file system path to the VM settings file (can
+ *  @param strConfigFile Local file system path to the VM settings file (can
  *                      be relative to the VirtualBox config directory).
  *  @param aId          UUID of the machine or NULL (see above).
@@ -518 +520 @@
  *  config is ignored and we always generate a fresh one.
  *
+ *  @param aParent  Associated parent object.
  *  @param strName  Name for the new machine; this overrides what is specified in config and is used
  *                  for the settings file as well.
@@ -610 +613 @@
 /**
  * Shared code between the various init() implementations.
- * @param aParent
+ * @param   aParent         The VirtualBox object.
+ * @param   strConfigFile   Settings file.
  * @return
  */
@@ -7255 +7259 @@
  * Adds the given IsModified_* flag to the dirty flags of the machine.
  * This must be called either during i_loadSettings or under the machine write lock.
- * @param fl
+ * @param   fl                       Flag
+ * @param   fAllowStateModification  If state modifications are allowed.
  */
 void Machine::i_setModified(uint32_t fl, bool fAllowStateModification /* = true */)
@@ -7268 +7273 @@
  * care of the write locking.
  *
- * @param   fModifications      The flag to add.
+ * @param   fModification            The flag to add.
+ * @param   fAllowStateModification  If state modifications are allowed.
  */
 void Machine::i_setModifiedLock(uint32_t fModification, bool fAllowStateModification /* = true */)
@@ -7279 +7285 @@
  *  Saves the registry entry of this machine to the given configuration node.
  *
- *  @param aEntryNode Node to save the registry entry to.
+ *  @param data     Machine registry data.
  *
  *  @note locks this object for reading.
@@ -7300 +7306 @@
  * machine settings file as the current directory.
  *
- * @param  aPath    Path to calculate the absolute path for.
+ * @param  strPath  Path to calculate the absolute path for.
  * @param  aResult  Where to put the result (used only on success, can be the
  *                  same Utf8Str instance as passed in @a aPath).
@@ -7453 +7459 @@
  * So instead we now use a timestamp.
  *
- * @param str
+ * @param strStateFilePath
  */
 
@@ -8891 +8897 @@
  *  Loads settings into mHWData.
  *
- *  @param data           Reference to the hardware settings.
- *  @param pDbg           Pointer to the debugging settings.
- *  @param pAutostart     Pointer to the autostart settings.
+ * @param puuidRegistry Registry ID.
+ * @param puuidSnapshot Snapshot ID
+ * @param data          Reference to the hardware settings.
+ * @param pDbg          Pointer to the debugging settings.
+ * @param pAutostart    Pointer to the autostart settings.
  */
 HRESULT Machine::i_loadHardware(const Guid *puuidRegistry,
@@ -9301 +9309 @@
  * Called from i_loadStorageControllers for a controller's devices.
  *
- * @param aStorageController
- * @param data
- * @param puuidRegistry media registry ID to set media to or NULL; see Machine::i_loadMachineDataFromSettings()
- * @param aSnapshotId  pointer to the snapshot ID if this is a snapshot machine
+ * @param   aStorageController
+ * @param   data
+ * @param   puuidRegistry   media registry ID to set media to or NULL; see
+ *                          Machine::i_loadMachineDataFromSettings()
+ * @param   puuidSnapshot   pointer to the snapshot ID if this is a snapshot machine
  * @return
  */
@@ -9572 +9581 @@
  *  Returns the snapshot with the given name or fails of no such snapshot.
  *
- *  @param aName        snapshot name to find
+ *  @param strName      snapshot name to find
  *  @param aSnapshot    where to return the found snapshot
  *  @param aSetError    true to set extended error info on failure
@@ -9965 +9974 @@
  *          saved and the global machine and media registries will therefore need
  *          updating.
+ * @param   aFlags  Flags.
  */
 HRESULT Machine::i_saveSettings(bool *pfNeedsGlobalSaveSettings,
@@ -10728 +10738 @@
  *                          many operations left as the number of hard disks
  *                          attached).
+ * @param aWeight           Weight of this operation.
  * @param aOnline           Whether the VM was online prior to this operation.
  *
@@ -11186 +11197 @@
  * can be searched as well if needed.
  *
- * @param list
+ * @param ll
  * @param aControllerName
  * @param aControllerPort
@@ -11212 +11223 @@
  * can be searched as well if needed.
  *
- * @param list
- * @param aControllerName
- * @param aControllerPort
- * @param aDevice
+ * @param ll
+ * @param pMedium
  * @return
  */
@@ -11237 +11246 @@
  * can be searched as well if needed.
  *
- * @param list
- * @param aControllerName
- * @param aControllerPort
- * @param aDevice
+ * @param ll
+ * @param id
  * @return
  */
@@ -11261 +11268 @@
  * from Machine::prepareUnregister() so it has been taken out for simplicity.
  *
- * @param pAttach Medium attachment to detach.
- * @param writeLock Machine write lock which the caller must have locked once. This may be released temporarily in here.
- * @param pSnapshot If NULL, then the detachment is for the current machine. Otherwise this is for a
- * SnapshotMachine, and this must be its snapshot.
+ * @param pAttach   Medium attachment to detach.
+ * @param writeLock Machine write lock which the caller must have locked once.
+ *                  This may be released temporarily in here.
+ * @param pSnapshot If NULL, then the detachment is for the current machine.
+ *                  Otherwise this is for a SnapshotMachine, and this must be
+ *                  its snapshot.
  * @return
  */
@@ -11337 +11346 @@
  * will be passed on to i_detachDevice which needs it for temporary unlocking.
  *
- * @param writeLock Machine lock from top-level caller; this gets passed to i_detachDevice.
- * @param pSnapshot Must be NULL when called for a "real" Machine or a snapshot object if called for a SnapshotMachine.
- * @param cleanupMode If DetachAllReturnHardDisksOnly, only hard disk media get added to llMedia; if
- * Full, then all media get added;
- *          otherwise no media get added.
- * @param llMedia Caller's list to receive Medium objects which got detached so caller can close() them, depending on cleanupMode.
+ * @param writeLock Machine lock from top-level caller; this gets passed to
+ *                  i_detachDevice.
+ * @param pSnapshot Must be NULL when called for a "real" Machine or a snapshot
+ *                  object if called for a SnapshotMachine.
+ * @param cleanupMode If DetachAllReturnHardDisksOnly, only hard disk media get
+ *                  added to llMedia; if Full, then all media get added;
+ *                  otherwise no media get added.
+ * @param llMedia   Caller's list to receive Medium objects which got detached so
+ *                  caller can close() them, depending on cleanupMode.
  * @return
  */

trunk/src/VBox/Main/src-server/MediumAttachmentImpl.cpp

@@ -96 +96 @@
  * @param aDevice           Device number on the port.
  * @param aType             Device type.
- * @param aImplicit
+ * @param aImplicit         
  * @param aPassthrough      Whether accesses are directly passed to the host drive.
- * @param aTempEject
+ * @param aTempEject        Whether guest-triggered eject results in unmounting the medium.
  * @param aNonRotational    Whether this medium is non-rotational (aka SSD).
- * @param aDiscard
+ * @param aDiscard          Whether this medium supports discarding unused blocks.
  * @param aHotPluggable     Whether this medium is hot-pluggable.
- * @param aBandwidthLimit   Bandwidth limit in Mbps.
+ * @param strBandwidthGroup Bandwidth group.
  */
 HRESULT MediumAttachment::init(Machine *aParent,

trunk/src/VBox/Main/src-server/MediumImpl.cpp

@@ -1441 +1441 @@
  * @param aParent       Parent medium disk or NULL for a root (base) medium.
  * @param aDeviceType   Device type of the medium.
- * @param uuidMachineRegistry The registry to which this medium should be added (global registry UUID or machine UUID).
+ * @param uuidMachineRegistry The registry to which this medium should be added
+ *                      (global registry UUID or machine UUID).
  * @param data          Configuration settings.
- * @param strMachineFolder The machine folder with which to resolve relative paths; if empty, then we use the VirtualBox home directory
+ * @param strMachineFolder The machine folder with which to resolve relative
+ *                      paths; if empty, then we use the VirtualBox home directory
+ * @param mediaTreeLock Autolock.
  *
  * @note Locks the medium tree for writing.
@@ -5441 +5444 @@
  * necessary consistency checks and place involved media to appropriate
  * states. If #mergeTo() is not called or fails, the state modifications
- * performed by this method must be undone by #cancelMergeTo().
+ * performed by this method must be undone by #i_cancelMergeTo().
  *
  * See #mergeTo() for more information about merging.
@@ -5451 +5454 @@
  * @param fLockMedia    Flag whether to lock the medium lock list or not.
  *                      If set to false and the medium lock list locking fails
- *                      later you must call #cancelMergeTo().
+ *                      later you must call #i_cancelMergeTo().
  * @param fMergeForward Resulting merge direction (out).
  * @param pParentForTarget New parent for target medium after merge (out).
@@ -5791 +5794 @@
  * any VM directly or in the snapshot, otherwise this method will assert.
  *
- * The #prepareMergeTo() method must be called prior to this method to place all
- * involved to necessary states and perform other consistency checks.
+ * The #i_prepareMergeTo() method must be called prior to this method to place
+ * all involved to necessary states and perform other consistency checks.
  *
  * If @a aWait is @c true then this method will perform the operation on the
@@ -5815 +5818 @@
  * When this method fails (regardless of the @a aWait mode), it is a caller's
  * responsibility to undo state changes and delete @a aMediumLockList using
- * #cancelMergeTo().
+ * #i_cancelMergeTo().
  *
  * If @a aProgress is not NULL but the object it points to is @c null then a new
@@ -5923 +5926 @@
 
 /**
- * Undoes what #prepareMergeTo() did. Must be called if #mergeTo() is not
+ * Undoes what #i_prepareMergeTo() did. Must be called if #mergeTo() is not
  * called or fails. Frees memory occupied by @a aMediumLockList and unlocks
  * the medium objects in @a aChildrenToReparent.
@@ -7530 +7533 @@
  * @param   pvUser          The opaque data passed on container creation.
  * @param   rc              The VBox error code.
- * @param   RT_SRC_POS_DECL Use RT_SRC_POS.
+ * @param   SRC_POS         Use RT_SRC_POS.
  * @param   pszFormat       Error message format string.
  * @param   va              Error message arguments.

trunk/src/VBox/Main/src-server/USBDeviceFilterImpl.cpp

@@ -859 +859 @@
  *
  *  @param aParent  Handle of the parent object.
+ *  @param data     Settings data.
  */
 HRESULT HostUSBDeviceFilter::init(Host *aParent,
@@ -929 +930 @@
  *
  *  @param aParent  Handle of the parent object.
+ *  @param aName    Filter name.
  */
 HRESULT HostUSBDeviceFilter::init(Host *aParent, IN_BSTR aName)
@@ -1247 +1249 @@
  *  @param  aIdx    The field index.
  *  @param  aStr    The new value.
- *  @param  aName   The translated field name (for error messages).
  *
  *  @return COM status.

trunk/src/VBox/Main/src-server/linux/HostHardwareLinux.cpp

@@ -893 +893 @@
     virtual ~hotplugNullImpl (void) {}
     /** @copydoc VBoxMainHotplugWaiter::Wait */
-    virtual int Wait (RTMSINTERVAL)
-    {
+    virtual int Wait (RTMSINTERVAL cMillies)
+    {
+        NOREF(cMillies);
         return VERR_NOT_SUPPORTED;
     }