Move BVolumeRoster docs to Haiku Book.

With this commit every class in the storage kit is now documented in the Haiku book! Thanks to Ingo, Axel, Vincent Dominguez, Tyler Dauwalder, and everyone who helped document these classes.
haiku · Feb 22, 2013 · 5dd0761 · 5dd0761
1 parent bcd9244
commit 5dd0761
Show file tree

Hide file tree

Showing 3 changed files with 155 additions and 93 deletions.
diff --git a/docs/user/storage/VolumeRoster.dox b/docs/user/storage/VolumeRoster.dox
@@ -0,0 +1,131 @@
+/*
+ * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Vincent Dominguez
+ *		John Scipione, jscipione@gmail.com
+ *		Ingo Weinhold, bonefish@users.sf.net
+ *
+ * Corresponds to:
+ *		headers/os/storage/VolumeRoster.h	hrev45306
+ *		src/kits/storage/VolumeRoster.cpp	hrev45306
+ */
+
+
+/*!
+	\file VolumeRoster.h
+	\ingroup storage
+	\ingroup libbe
+	\brief Provides the BVolumeRoster class.
+*/
+
+
+/*!
+	\class BVolumeRoster
+	\ingroup storage
+	\ingroup libbe
+	\brief Provides an interface for iterating through available volumes
+	       and watching for mounting/unmounting.
+
+	This class wraps the next_dev() function for iterating through the
+	list of available volumes and watch_node()/stop_watching() for
+	watching volumes.
+*/
+
+
+/*!
+	\fn BVolumeRoster::BVolumeRoster()
+	\brief Creates a BVolumeRoster object. The object is ready to be used.
+*/
+
+
+/*!
+	\fn BVolumeRoster::~BVolumeRoster()
+	\brief Deletes the volume roster and frees all associated resources.
+
+	If a watch was activated (by StartWatching()), it is deactivated.
+*/
+
+
+
+/*!
+	\fn status_t BVolumeRoster::GetNextVolume(BVolume *volume)
+	\brief Fills out the passed in BVolume object with the next available
+	       volume.
+
+	\param volume A pointer to a pre-allocated BVolume object to be
+	       initialized to the next available volume.
+
+	\return A status code.
+	\retval B_OK Everything went fine.
+	\retval B_BAD_VALUE The last volume in the list was already returned.
+*/
+
+
+/*!
+	\fn void BVolumeRoster::Rewind()
+	\brief Rewinds the list of available volumes back to the first item.
+
+	The next call to GetNextVolume() will return the first available volume.
+*/
+
+
+/*!
+	\fn status_t BVolumeRoster::GetBootVolume(BVolume *volume)
+	\brief Fills out the passed in BVolume object with the boot volume.
+
+	Currently, this method looks for the volume that is mounted at "/boot".
+	The only way to fool the system into thinking that there is not a boot
+	volume is to rename "/boot" -- but, please refrain from doing this.
+
+	\param volume A pointer to a pre-allocated BVolume to be initialized to
+		   refer to the boot volume.
+
+	\return A status code, \c B_OK if everything went fine or an error code
+	        otherwise.
+*/
+
+
+/*!
+	\fn status_t BVolumeRoster::StartWatching(BMessenger messenger)
+	\brief Starts watching the available volumes for changes.
+
+	Notifications are sent to the specified target whenever a volume is
+	mounted or unmounted. The format of the notification messages is
+	described under watch_node(). Actually BVolumeRoster just provides a
+	more convenient interface for it.
+
+	If StartWatching() has been called before with another target and no
+	StopWatching() since, StopWatching() is called first, so that the former
+	target won't receive any notifications anymore.
+
+	When the object is destroyed all watching ends as well.
+
+	\param messenger The target which the notification messages are sent.
+
+	\return A status code.
+	\retval B_OK Everything went fine.
+	\retval B_BAD_VALUE The supplied BMessenger was invalid.
+	\retval B_NO_MEMORY There was insufficient memory to carry out this
+	        operation.
+
+	\see watch_node()
+*/
+
+
+/*!
+	\fn void BVolumeRoster::StopWatching()
+	\brief Stops watching volumes initiated by StartWatching().
+
+	\see stop_watching()
+*/
+
+
+/*!
+	\fn BMessenger BVolumeRoster::Messenger() const
+	\brief Returns the messenger currently watching the volume list.
+
+	\return A messenger to the target currently watching the volume list, or
+			an invalid messenger if not watching.
+*/
diff --git a/headers/os/storage/VolumeRoster.h b/headers/os/storage/VolumeRoster.h
@@ -36,8 +36,16 @@ class BVolumeRoster {
 
 private:
 			int32				fCookie;
+									// The iteration cookie for next_dev()
+									// Initialized to 0
 			BMessenger*			fTarget;
+									// BMessenger referring to the target to
+									// which the watching notification
+									// messages are sent. The object is
+									// allocated and owned by the roster,
+									// or NULL if not watching.
 			uint32				_reserved[3];
+									// FBC
 };
 
 

diff --git a/src/kits/storage/VolumeRoster.cpp b/src/kits/storage/VolumeRoster.cpp
@@ -6,10 +6,7 @@
 //
 //	Description:	BVolumeRoster class
 // ----------------------------------------------------------------------
-/*!
-	\file VolumeRoster.cpp
-	BVolumeRoster implementation.
-*/
+
 
 #include <errno.h>
 #include <new>
@@ -21,71 +18,32 @@
 #include <NodeMonitor.h>
 #include <VolumeRoster.h>
 
+
 static const char kBootVolumePath[] = "/boot";
 
 using namespace std;
 
+
 #ifdef USE_OPENBEOS_NAMESPACE
 namespace OpenBeOS {
 #endif
 
-/*!
-	\class BVolumeRoster
-	\brief A roster of all volumes available in the system
-	
-	Provides an interface for iterating through the volumes available in
-	the system and watching volume mounting/unmounting.
-
-	The class wraps the next_dev() function for iterating through the
-	volume list and the watch_node()/stop_watching() for the watching
-	features.
-
-	\author Vincent Dominguez
-	\author <a href='mailto:bonefish@users.sf.net'>Ingo Weinhold</a>
-	
-	\version 0.0.0
-*/
 
-/*!	\var dev_t BVolumeRoster::fCookie
-	\brief The iteration cookie for next_dev(). Initialized with 0.
-*/
-
-/*!	\var dev_t BVolumeRoster::fTarget
-	\brief BMessenger referring to the target to which the watching
-		   notification messages are sent.
-
-	The object is allocated and owned by the roster. \c NULL, if not watching.
-*/
-
-// constructor
-/*!	\brief Creates a new BVolumeRoster.
-
-	The object is ready to be used.
-*/
 BVolumeRoster::BVolumeRoster()
 	: fCookie(0),
 	  fTarget(NULL)
 {
 }
 
-// destructor
-/*!	\brief Frees all resources associated with this object.
 
-	If a watching was activated on (StartWatching()), it is deactived.
-*/
+// Deletes the volume roster and frees all associated resources.
 BVolumeRoster::~BVolumeRoster()
 {
 	StopWatching();
 }
 
-// GetNextVolume
-/*!	\brief Returns the next volume in the list of available volumes.
-	\param volume A pointer to a pre-allocated BVolume to be initialized to
-		   refer to the next volume in the list of available volumes.
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_BAD_VALUE: The last volume in the list has already been returned.
-*/
+
+// Fills out the passed in BVolume object with the next available volume.
 status_t
 BVolumeRoster::GetNextVolume(BVolume *volume)
 {
@@ -104,29 +62,16 @@ BVolumeRoster::GetNextVolume(BVolume *volume)
 	return error;
 }
 
-// Rewind
-/*! \brief Rewinds the list of available volumes such that the next call to
-		   GetNextVolume() will return the first element in the list.
-*/
+
+// Rewinds the list of available volumes back to the first item.
 void
 BVolumeRoster::Rewind()
 {
 	fCookie = 0;
 }
 
-// GetBootVolume
-/*!	\brief Returns the boot volume.
-
-	Currently, this function looks for the volume that is mounted at "/boot".
-	The only way to fool the system into thinking that there is not a boot
-	volume is to rename "/boot" -- but, please refrain from doing so...(:o(
 
-	\param volume A pointer to a pre-allocated BVolume to be initialized to
-		   refer to the boot volume.
-	\return
-	- \c B_OK: Everything went fine.
-	- an error code otherwise
-*/
+// Fills out the passed in BVolume object with the boot volume.
 status_t
 BVolumeRoster::GetBootVolume(BVolume *volume)
 {
@@ -145,27 +90,8 @@ BVolumeRoster::GetBootVolume(BVolume *volume)
 	return error;
 }
 
-// StartWatching
-/*!	\brief Starts watching the list of volumes available in the system.
-
-	Notifications are sent to the specified target whenever a volume is
-	mounted or unmounted. The format of the notification messages is
-	described under watch_node(). Actually BVolumeRoster just provides a
-	more convenient interface for it.
-
-	If StartWatching() has been called before with another target and no
-	StopWatching() since, StopWatching() is called first, so that the former
-	target won't receive any notifications anymore.
-
-	When the object is destroyed all watching has an end as well.
 
-	\param messenger The target to which the notification messages shall be
-		   sent.
-	\return
-	- \c B_OK: Everything went fine.
-	- \c B_BAD_VALUE: The supplied BMessenger is invalid.
-	- \c B_NO_MEMORY: Insufficient memory to carry out this operation.
-*/
+// Starts watching the available volumes for changes.
 status_t
 BVolumeRoster::StartWatching(BMessenger messenger)
 {
@@ -188,9 +114,8 @@ BVolumeRoster::StartWatching(BMessenger messenger)
 	return error;
 }
 
-// StopWatching
-/*!	\brief Stops volume watching initiated with StartWatching() before.
-*/
+
+// Stops watching volumes initiated by StartWatching().
 void
 BVolumeRoster::StopWatching()
 {
@@ -201,22 +126,20 @@ BVolumeRoster::StopWatching()
 	}
 }
 
-// Messenger
-/*!	\brief Returns a messenger to the target currently watching the volume
-		   list.
-	\return A messenger to the target currently watching the volume list, or
-			an invalid messenger, if noone is currently watching.
-*/
+
+// Returns the messenger currently watching the volume list.
 BMessenger
 BVolumeRoster::Messenger() const
 {
 	return (fTarget ? *fTarget : BMessenger());
 }
 
+
 // FBC
 void BVolumeRoster::_SeveredVRoster1() {}
 void BVolumeRoster::_SeveredVRoster2() {}
 
+
 #ifdef USE_OPENBEOS_NAMESPACE
 }
 #endif