* Removed deprecated functions.

* The documented the notify_*() functions - only notify_listener() was deprecated
  among them.
* Replaced spaces with tabs - there is no reason to deviate from the standard we're
  using everywhere else.
* Completed the docs here and there.


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21615 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/drivers/fs_interface.dox

@@ -1,10 +1,12 @@
-/*
+/*
  * Copyright 2007 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
  *		Ingo Weinhold 
  *		Niels Sascha Reedijk <[email protected]>
+ *		Axel Dörfler, [email protected]
+ *
  * Corresponds to:
  *		/trunk/headers/os/drivers/fs_interface.h rev 21568
  */
@@ -18,26 +20,6 @@
 	how to get started with writing file system modules.
 */
 
-///// Typedefs /////
-
-/*! 
-  \typedef typedef void *fs_volume
-  \brief Private data structure for the filesystem to store data associated
-    with volumes.
-*/
-
-/*!
-  \typedef typedef void *fs_cookie
-  \brief Private data structure that is passed to the filesystem when it is
-    called.
-*/
-
-/*!
-  \typedef typedef void *fs_vnode
-  \brief Private data structure that is passed to the filesystem when it is
-    operating on vnodes.
-*/
-
 ///// write_stat_mask //////
 
 /*!
@@ -111,8 +93,12 @@
 
 /*!
 	\def B_CURRENT_FS_API_VERSION
-  \brief Constant that defines the version of the filesystem API that your
+	\brief Constant that defines the version of the file system API that your
 		filesystem conforms to.
+	
+	The module name that exports the interface to your file system has to
+	end with this constant as in:
+	\code "file_systems/myfs" B_CURRENT_FS_API_VERSION
 */
 
 ///// file_system_module_info /////
@@ -140,6 +126,9 @@
 /*!
 	\var const char *file_system_module_info::pretty_name
 	\brief A NULL-terminated string with a 'pretty' name for you file system.
+
+	Note, if a system wide disk device type constant exists for your file system,
+	it should equal this identifier.
 */
 
 //! @}
@@ -1554,7 +1543,7 @@
 
 //! @}
 
-///// Global Functions /////
+///// Vnode functions /////
 
 /*!
 	\fn status_t new_vnode(dev_t mountID, ino_t vnodeID,
@@ -1565,13 +1554,17 @@
 	The effect of the function is similar to publish_vnode(), but the vnode
 	remains in an unpublished state, with the effect that a subsequent
 	remove_vnode() will just delete the vnode and not invoke the file system's
-  \link file_system_module_info::remove_vnode remove_vnode() \endlink is not
-  invoked.
+	\link file_system_module_info::remove_vnode remove_vnode() \endlink when
+	the final reference is put down.
 
 	If the vnode shall be kept, publish_vnode() has to be invoked afterwards to
 	mark the vnode published. The combined effect is the same as only invoking
 	publish_vnode().
 
+	You'll usually use this function to secure a vnode ID from being reused
+	while you are in the process of creating the entry. Note that this function
+	will panic in case you call it for an existing vnode ID. 
+
 	The function fails, if the vnode does already exist.
 
 	\param mountID The ID of the volume.
@@ -1595,6 +1588,8 @@
 	sequence of new_vnode() and publish_vnode() results in just one reference as
 	well. The reference can be surrendered by calling put_vnode().
 
+	This call is equivalent to the former R5 new_vnode() function.
+
 	\param mountID The ID of the volume.
 	\param vnodeID The ID of the node.
 	\param privateNode The private data handle to be associated with the node.
@@ -1673,66 +1668,65 @@
 	\return \c B_OK if everything went fine, another error code otherwise.
 */
 
-///// Deprecated Global Functions
+///// Notification Functions
 
 /*!
-  \name Deprecated functions
+	\name Notification Functions
 
-  The following list of functions should not be used, and could be removed even
-  before the release of Haiku R1.
-*/
+	The following functions are used to implement the node monitor functionality
+	in your file system. Whenever one of the below mentioned events occur, you
+	have to call them.
 
-//! @{
-
-/*!
-  \fn status_t notify_listener(int op, dev_t device, ino_t parentNode,
-					ino_t toParentNode, ino_t node, const char *name)
-  \brief Deprecated. This feature will be removed in future versions.
+	The node monitor will then notify all registered listeners for the nodes
+	that changed.
 */ 
 
 /*!
 	\fn status_t notify_entry_created(dev_t device, ino_t directory,
 					const char *name, ino_t node)
-  \brief Deprecated. This feature will be removed in future versions.
+	\brief Notifies listeners that a file system entry has been created.
 */
 
 /*!
 	\fn status_t notify_entry_removed(dev_t device, ino_t directory,
 					const char *name, ino_t node)
-  \brief Deprecated. This feature will be removed in future versions.
+	\brief Notifies listeners that a file system entry has been removed.
 */
 
 /*!
 	\fn status_t notify_entry_moved(dev_t device, ino_t fromDirectory,
 					const char *fromName, ino_t toDirectory,
 					const char *toName, ino_t node)
-  \brief Deprecated. This feature will be removed in future versions.
+	\brief Notifies listeners that a file system entry has been moved to
+		another directory.
 */
 
 /*!
 	\fn status_t notify_stat_changed(dev_t device, ino_t node,
 					uint32 statFields)
-  \brief Deprecated. This feature will be removed in future versions.
+	\brief Notifies listeners that certain \a statFields of a file system entry
+		were updated.
 */
 
 /*!
 	\fn status_t notify_attribute_changed(dev_t device, ino_t node,
 					const char *attribute, int32 cause)
-  \brief Deprecated. This feature will be removed in future versions.
+	\brief Notifies listeners that an attribute of a file system entry has been
+		changed.
 */
 
 /*!
 	\fn status_t notify_query_entry_created(port_id port, int32 token,
 					dev_t device, ino_t directory, const char *name,
 					ino_t node)
-  \brief Deprecated. This feature will be removed in future versions.
+	\brief Notifies listeners that an entry has entered the result set of a live query.
 */
 
 /*!
 	\fn status_t notify_query_entry_removed(port_id port, int32 token,
 					dev_t device, ino_t directory, const char *name,
 					ino_t node)
-  \brief Deprecated. This feature will be removed in future versions.
+	\brief Notifies listeners that an entry has left the result set of a live query.
 */
 
 //! @}