Add BSymLink class docs to Haiku Book

docs/user/storage/SymLink.dox

@@ -0,0 +1,159 @@
+/*
+ * Copyright 2002-2013 Haiku Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Tyler Dauwalder
+ *		John Scipione, [email protected]
+ *		Ingo Weinhold, [email protected]
+ *
+ * Corresponds to:
+ *		headers/os/storage/Symlink.h	hrev45306
+ *		src/kits/storage/Symlink.cpp	hrev45306
+ */
+
+
+/*!
+	\file Symlink.h
+	\ingroup storage
+	\ingroup libbe
+	\brief Provides the BSymLink class.
+*/
+
+
+/*!
+	\class BSymLink
+	\ingroup storage
+	\ingroup libbe
+	\brief Provides an interface for creating, manipulating, and accessing
+	       the contents of symbolic links.
+*/
+
+
+/*!
+	\fn BSymLink::BSymLink()
+	\brief Creates an uninitialized BSymLink object.
+*/
+
+
+/*!
+	\fn BSymLink::BSymLink(const BSymLink &link)
+	\brief Creates a copy of the supplied BSymLink object.
+
+	\param link The BSymLink object to be copied.
+*/
+
+
+/*!
+	\fn BSymLink::BSymLink(const entry_ref *ref)
+	\brief Creates a BSymLink object and initializes it to the symbolic link
+	       referred to by the supplied entry_ref.
+
+	\param ref the entry_ref referring to the symbolic link.
+*/
+
+
+/*!
+	\fn BSymLink::BSymLink(const BEntry *entry)
+	\brief Creates a BSymLink object and initializes it to the symbolic link
+	       referred to by the supplied BEntry.
+
+	\param entry The BEntry referring to the symbolic link.
+*/
+
+
+/*!
+	\fn BSymLink::BSymLink(const char *path)
+	\brief Creates a BSymLink object and initializes it to the symbolic link
+	       referred to by the supplied path name.
+
+	\param path The path of the symbolic link.
+*/
+
+
+/*!
+	\fn BSymLink::BSymLink(const BDirectory *dir, const char *path)
+	\brief Creates a BSymLink object and initializes it to the symbolic link
+	       referred to by the supplied path name relative to the specified
+	       BDirectory.
+
+	\param dir The base BDirectory.
+	\param path The path of the symbolic link relative to \a dir.
+*/
+
+
+/*!
+	\fn BSymLink::~BSymLink()
+	\brief Destroys the object and frees all allocated resources.
+
+	If the BSymLink was properly initialized, the file descriptor of the
+	symbolic link is also closed.
+*/
+
+
+/*!
+	\fn ssize_t BSymLink::ReadLink(char *buffer, size_t size)
+	\brief Reads the contents of the symbolic link into \a buffer.
+
+	The string written to the buffer is guaranteed to be \c NULL terminated.
+
+	\param buffer The buffer to read the symlink's contents into.
+	\param size The size of \a buffer.
+
+	\return The number of bytes written into the buffer or an error code.
+	\retval B_BAD_VALUE \a buf was \c NULL or the object didn't refer to a
+	        symbolic link.
+	\retval B_FILE_ERROR The object was not initialized.
+*/
+
+
+/*!
+	\fn ssize_t BSymLink::MakeLinkedPath(const char *dirPath, BPath *path)
+	\brief Combines a directory path and the contents of this symbolic link to
+	       form an absolute path.
+
+	\param dirPath The base directory path to combine with the symbolic link.
+	\param path The BPath object to be set to the resulting absolute path.
+
+	\return The length of the resulting path name or an error code.
+	\retval B_BAD_VALUE \a dirPath or \a path was \c NULL or the object didn't
+	        refer to a symbolic link.
+	\retval B_FILE_ERROR The object was not initialized.
+	\retval B_NAME_TOO_LONG The resulting path name was too long to fit.
+*/
+
+
+/*!
+	\fn ssize_t BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path)
+	\brief Combines a directory path and the contents of this symbolic link to
+	       form an absolute path.
+
+	\param dir The base BDirectory object to combine with the symbolic link.
+	\param path the BPath object to be set to the resulting absolute path.
+
+	\return The length of the resulting path name or an error code.
+	\retval B_BAD_VALUE \a dir or \a path was \c NULL or the object didn't
+	        refer to a symbolic link.
+	\retval B_FILE_ERROR The object was not initialized.
+	\retval B_NAME_TOO_LONG The resulting path name was too long to fit.
+*/
+
+
+/*!
+	\fn bool BSymLink::IsAbsolute()
+	\brief Returns whether or not the object refers to an absolute path.
+
+	/return \c true if the object is properly initialized and the symbolic
+	        link refers to an absolute path, \c false otherwise.
+*/
+
+
+/*!
+	\fn int BSymLink::get_fd() const
+	\brief Returns the file descriptor of the BSymLink.
+
+	This method should be used instead of accessing the private \c fFd member
+	of the BNode directly.
+
+	\return The object's file descriptor, or -1 if not properly initialized.
+*/

headers/os/storage/SymLink.h

@@ -9,50 +9,44 @@
 #include <Node.h>
 #include <StorageDefs.h>
 
+
 class BDirectory;
 class BPath;
 
-
-/*!
-	\class BSymLink
-	\brief A symbolic link in the filesystem
-	
-	Provides an interface for manipulating symbolic links.
-
-	\author <a href='mailto:[email protected]'>Ingo Weinhold</a>
-	
-	\version 0.0.0
-*/
 class BSymLink : public BNode {
 public:
-	BSymLink();
+								BSymLink();
-	BSymLink(const BSymLink &link);
+								BSymLink(const BSymLink &link);
-	BSymLink(const entry_ref *ref);
+								BSymLink(const entry_ref *ref);
-	BSymLink(const BEntry *entry);
+								BSymLink(const BEntry *entry);
-	BSymLink(const char *path);
+								BSymLink(const char *path);
-	BSymLink(const BDirectory *dir, const char *path);
+								BSymLink(const BDirectory *dir,
-	virtual ~BSymLink();
+								         const char *path);
+	virtual						~BSymLink();
 
-	ssize_t ReadLink(char *buf, size_t size);
+			ssize_t				ReadLink(char *buf, size_t size);
 
-	ssize_t MakeLinkedPath(const char *dirPath, BPath *path);
+			ssize_t				MakeLinkedPath(const char *dirPath,
-	ssize_t MakeLinkedPath(const BDirectory *dir, BPath *path);
+								               BPath *path);
+			ssize_t				MakeLinkedPath(const BDirectory *dir,
+								               BPath *path);
 
-	bool IsAbsolute();
+			bool				IsAbsolute();
 
 private:
-	virtual void _MissingSymLink1();
+	virtual	void				_MissingSymLink1();
-	virtual void _MissingSymLink2();
+	virtual	void				_MissingSymLink2();
-	virtual void _MissingSymLink3();
+	virtual	void				_MissingSymLink3();
-	virtual void _MissingSymLink4();
+	virtual	void				_MissingSymLink4();
-	virtual void _MissingSymLink5();
+	virtual	void				_MissingSymLink5();
-	virtual void _MissingSymLink6();
+	virtual	void				_MissingSymLink6();
 
-	uint32 _reservedData[4];
+			uint32				_reservedData[4];
-	BEntry *fSecretEntry;
+			BEntry*				fSecretEntry;
 
 private:
-	int get_fd() const;
+			int					get_fd() const;
 };
 
+
 #endif	// _SYM_LINK_H

src/kits/storage/SymLink.cpp

@@ -8,11 +8,6 @@
  */
 
 
-/*!	\file SymLink.cpp
-	BSymLink implementation.
-*/
-
-
 #include <new>
 #include <string.h>
 
@@ -25,18 +20,17 @@
 
 #include "storage_support.h"
 
+
 using namespace std;
 
 
-//! Creates an uninitialized BSymLink object.
+// Creates an uninitialized BSymLink object.
 BSymLink::BSymLink()
 {
 }
 
 
-//! Creates a copy of the supplied BSymLink.
+// Creates a copy of the supplied BSymLink object.
-/*!	\param link the BSymLink object to be copied
-*/
 BSymLink::BSymLink(const BSymLink &link)
 	:
 	BNode(link)
@@ -44,10 +38,8 @@ BSymLink::BSymLink(const BSymLink &link)
 }
 
 
-/*! \brief Creates a BSymLink and initializes it to the symbolic link referred
+// Creates a BSymLink object and initializes it to the symbolic link referred
-	to by the supplied entry_ref.
+// to by the supplied entry_ref.
-	\param ref the entry_ref referring to the symbolic link
-*/
 BSymLink::BSymLink(const entry_ref *ref)
 	:
 	BNode(ref)
@@ -55,20 +47,16 @@ BSymLink::BSymLink(const entry_ref *ref)
 }
 
 
-/*! \brief Creates a BSymLink and initializes it to the symbolic link referred
+// Creates a BSymLink object and initializes it to the symbolic link referred
-	to by the supplied BEntry.
+// to by the supplied BEntry.
-	\param entry the BEntry referring to the symbolic link
-*/
 BSymLink::BSymLink(const BEntry *entry)
 		: BNode(entry)
 {
 }
 
 
-/*! \brief Creates a BSymLink and initializes it to the symbolic link referred
+// Creates a BSymLink object and initializes it to the symbolic link referred
-	to by the supplied path name.
+// to by the supplied path name.
-	\param path the symbolic link's path name 
-*/
 BSymLink::BSymLink(const char *path)
 	:
 	BNode(path)
@@ -76,12 +64,8 @@ BSymLink::BSymLink(const char *path)
 }
 
 
-/*! \brief Creates a BSymLink and initializes it to the symbolic link referred
+// Creates a BSymLink object and initializes it to the symbolic link referred
-	to by the supplied path name relative to the specified BDirectory.
+// to by the supplied path name relative to the specified BDirectory.
-	\param dir the BDirectory, relative to which the symbolic link's path name
-		   is given
-	\param path the symbolic link's path name relative to \a dir
-*/
 BSymLink::BSymLink(const BDirectory *dir, const char *path)
 	:
 	BNode(dir, path)
@@ -89,31 +73,19 @@ BSymLink::BSymLink(const BDirectory *dir, const char *path)
 }
 
 
-//! Frees all allocated resources.
+// Destroys the object and frees all allocated resources.
-/*! If the BSymLink is properly initialized, the symbolic link's file
-	descriptor is closed.
-*/
 BSymLink::~BSymLink()
 {
 }
 
 
-//! Reads the contents of the symbolic link into a buffer.
+// Reads the contents of the symbolic link into a buffer.
-/*!	The string written to the buffer will be null-terminated.
-	\param buf the buffer
-	\param size the size of the buffer
-	\return
-	- the number of bytes written into the buffer
-	- \c B_BAD_VALUE: \c NULL \a buf or the object doesn't refer to a symbolic
-	  link.
-	- \c B_FILE_ERROR: The object is not initialized.
-	- some other error code
-*/
 ssize_t
 BSymLink::ReadLink(char *buffer, size_t size)
 {
-	if (!buffer)
+	if (buffer == NULL)
 		return B_BAD_VALUE;
+
 	if (InitCheck() != B_OK)
 		return B_FILE_ERROR;
 
@@ -125,57 +97,40 @@ BSymLink::ReadLink(char *buffer, size_t size)
 	// null-terminate
 	if (linkLen >= size)
 		return B_BUFFER_OVERFLOW;
+
 	buffer[linkLen] = '\0';
 
 	return linkLen;
 }
 
 
-/*!	\brief Combines a directory path and the contents of this symbolic link to
+// Combines a directory path and the contents of this symbolic link to form an
-	an absolute path.
+// absolute path.
-	\param dirPath the path name of the directory
-	\param path the BPath object to be set to the resulting path name
-	\return
-	- \c the length of the resulting path name,
-	- \c B_BAD_VALUE: \c NULL \a dirPath or \a path or the object doesn't
-		 refer to a symbolic link.
-	- \c B_FILE_ERROR: The object is not initialized.
-	- \c B_NAME_TOO_LONG: The resulting path name is too long.
-	- some other error code
-*/
 ssize_t
 BSymLink::MakeLinkedPath(const char *dirPath, BPath *path)
 {
-	// BeOS seems to convert the dirPath to a BDirectory, which causes links to
+	// BeOS seems to convert the dirPath to a BDirectory, which causes links
-	// be resolved.
+	// to be resolved. This means that the dirPath must exist!
-	// This does also mean that the dirPath must exist!
+	if (dirPath == NULL || path == NULL)
-	if (!dirPath || !path)
 		return B_BAD_VALUE;
+
 	BDirectory dir(dirPath);
 	ssize_t result = dir.InitCheck();
 	if (result == B_OK)
 		result = MakeLinkedPath(&dir, path);
+
 	return result;
 }
 
 
-/*!	\brief Combines a directory path and the contents of this symbolic link to
+// Combines a directory path and the contents of this symbolic link to form an
-	an absolute path.
+// absolute path.
-	\param dir the BDirectory referring to the directory
-	\param path the BPath object to be set to the resulting path name
-	\return
-	- \c the length of the resulting path name,
-	- \c B_BAD_VALUE: \c NULL \a dir or \a path or the object doesn't
-		 refer to a symbolic link.
-	- \c B_FILE_ERROR: The object is not initialized.
-	- \c B_NAME_TOO_LONG: The resulting path name is too long.
-	- some other error code
-*/
 ssize_t
 BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path)
 {
-	if (!dir || !path)
+	if (dir == NULL || path == NULL)
 		return B_BAD_VALUE;
+
 	char contents[B_PATH_NAME_LENGTH];
 	ssize_t result = ReadLink(contents, sizeof(contents));
 	if (result >= 0) {
@@ -183,19 +138,16 @@ BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path)
 			result = path->SetTo(contents);
 		else
 			result = path->SetTo(dir, contents);
+
 		if (result == B_OK)
 			result = strlen(path->Path());
 	}
+
 	return result;
 }
 
 
-//!	Returns whether this BSymLink refers to an absolute link.
+// Returns whether or not the object refers to an absolute path.
-/*!	/return
-	- \c true, if the object is properly initialized and the symbolic link it
-	  refers to is an absolute link,
-	- \c false, otherwise.
-*/
 bool
 BSymLink::IsAbsolute()
 {
@@ -203,6 +155,7 @@ BSymLink::IsAbsolute()
 	bool result = (ReadLink(contents, sizeof(contents)) >= 0);
 	if (result)
 		result = BPrivate::Storage::is_absolute_path(contents);
+
 	return result;
 }
 
@@ -215,10 +168,7 @@ void BSymLink::_MissingSymLink5() {}
 void BSymLink::_MissingSymLink6() {}
 
 
-//! Returns the BSymLink's file descriptor.
+// Returns the file descriptor of the BSymLink.
-/*! To be used instead of accessing the BNode's private \c fFd member directly.
-	\return the file descriptor, or -1, if not properly initialized.
-*/
 int
 BSymLink::get_fd() const
 {