Some doxygen comment cleanup for (Abstract)FilesystemNode

svn-id: r22304

2 files changed, 59 insertions, 62 deletions

diff --git a/backends/fs/abstract-fs.h b/backends/fs/abstract-fs.h
index 5bba75756c..a01ad11c69 100644
--- a/backends/fs/abstract-fs.h
+++ b/backends/fs/abstract-fs.h
@@ -34,6 +34,10 @@ typedef Common::Array<AbstractFilesystemNode *>	AbstractFSList;
 /**
  * Abstract file system node. Private subclasses implement the actual
  * functionality.
+ *
+ * Most of the methods correspond directly to methods in class FilesystemNode,
+ * so if they are not documented here, look there for more information about
+ * the semantics.
  */
 class AbstractFilesystemNode {
 protected:
@@ -80,47 +84,10 @@ protected:
 public:
 	virtual ~AbstractFilesystemNode() {}
 
-	/**
-	 * Return a human readable string for this node, usable for display (e.g.
-	 * in the GUI code). Do *not* rely on it being usable for anything else,
-	 * like constructing paths!
-	 * @return the display name
-	 */
 	virtual String displayName() const = 0;
-
-	/**
-	 * Is this node valid? Returns true if the file/directory pointed
-	 * to by this node exists, false otherwise.
-	 *
-	 * @todo Maybe rename this to exists() ? Or maybe even distinguish between
-	 * the two? E.g. a path may be non-existant but valid, while another might
-	 * be completely invalid). But do we ever need to make that distinction?
-	 */
 	virtual bool isValid() const = 0;
-
-	/**
-	 * Is this node pointing to a directory?
-	 * @todo Currently we assume that a valid node that is not a directory
-	 * automatically is a file (ignoring things like symlinks). That might
-	 * actually be OK... but we could still add an isFile method. Or even replace
-	 * isValid and isDirectory by a getType() method that can return values like
-	 * kDirNodeType, kFileNodeType, kInvalidNodeType.
-	 */
 	virtual bool isDirectory() const = 0;
-
-	/**
-	 * Return a string representation of the file which can be passed to fopen(),
-	 * and is suitable for archiving (i.e. writing to the config file).
-	 * This will usually be a 'path' (hence the name of the method), but can
-	 * be anything that fulfilly the above criterions.
-	 */
 	virtual String path() const = 0;
-
-	/**
-	 * Return a list of child nodes of this directory node. If called
-	 * on a node that does not represent a directory, an error is triggered.
-	 * @todo Rename this to listChildren.
-	 */
 	virtual AbstractFSList listDir(ListMode mode) const = 0;
 
 
diff --git a/backends/fs/fs.h b/backends/fs/fs.h
index 75adc57417..38b46db031 100644
--- a/backends/fs/fs.h
+++ b/backends/fs/fs.h
@@ -22,9 +22,24 @@
 #ifndef BACKENDS_FS_H
 #define BACKENDS_FS_H
 
+#include "common/array.h"
+#include "common/str.h"
+
+class FilesystemNode;
+class AbstractFilesystemNode;
+
+
+/**
+ * List of multiple file system nodes. E.g. the contents of a given directory.
+ * This is subclass instead of just a typedef so that we can use forward
+ * declarations of it in other places.
+ */
+class FSList : public Common::Array<FilesystemNode> {};
+
+
 /*
- * The API described in this header is meant to allow for file system browsing in a
- * portable fashions. To this ends, multiple or single roots have to be supported
+ * FilesystemNode provides an abstraction for file pathes, allowing for portable
+ * file system browsing. To this ends, multiple or single roots have to be supported
  * (compare Unix with a single root, Windows with multiple roots C:, D:, ...).
  *
  * To this end, we abstract away from paths; implementations can be based on
@@ -45,28 +60,6 @@
  * And if we ever want to support devices with no FS in the classical sense (Palm...),
  * we can build upon this.
  */
-
-/*
- * TODO - Instead of starting with getRoot(), we should rather add a getDefaultDir()
- * call that on Unix might return the current dir or the users home dir...
- * i.e. the root dir is usually not the best starting point for browsing.
- */
-
-#include "common/array.h"
-#include "common/str.h"
-
-class FilesystemNode;
-class AbstractFilesystemNode;
-
-
-/**
- * List of multiple file system nodes. E.g. the contents of a given directory.
- * This is subclass instead of just a typedef so that we can use forward
- * declarations of it in other places.
- */
-class FSList : public Common::Array<FilesystemNode> {};
-
-
 class FilesystemNode {
 	typedef Common::String String;
 private:
@@ -87,7 +80,7 @@ public:
 
 
 	/**
-	 * Create a new FilesystemNode refering to the specified path. This is
+	 * Create a new FilesystemNode referring to the specified path. This is
 	 * the counterpart to the path() method.
 	 */
 	FilesystemNode(const String &path);
@@ -112,10 +105,47 @@ public:
 	 */
 	FilesystemNode getChild(const String &name) const;
 
+	/**
+	 * Return a list of child nodes of this directory node. If called
+	 * on a node that does not represent a directory, an error is triggered.
+	 * @todo Rename this to listChildren or getChildren.
+	 */
 	virtual FSList listDir(ListMode mode = kListDirectoriesOnly) const;
+
+	/**
+	 * Return a human readable string for this node, usable for display (e.g.
+	 * in the GUI code). Do *not* rely on it being usable for anything else,
+	 * like constructing paths!
+	 * @return the display name
+	 */
 	virtual String displayName() const;
+
+	/**
+	 * Is this node valid? Returns true if the file/directory pointed
+	 * to by this node exists, false otherwise.
+	 *
+	 * @todo Maybe rename this to exists() ? Or maybe even distinguish between
+	 * the two? E.g. a path may be non-existant but valid, while another might
+	 * be completely invalid). But do we ever need to make that distinction?
+	 */
 	virtual bool isValid() const;
+
+	/**
+	 * Is this node pointing to a directory?
+	 * @todo Currently we assume that a valid node that is not a directory
+	 * automatically is a file (ignoring things like symlinks). That might
+	 * actually be OK... but we could still add an isFile method. Or even replace
+	 * isValid and isDirectory by a getType() method that can return values like
+	 * kDirNodeType, kFileNodeType, kInvalidNodeType.
+	 */
 	virtual bool isDirectory() const;
+
+	/**
+	 * Return a string representation of the file which can be passed to fopen(),
+	 * and is suitable for archiving (i.e. writing to the config file).
+	 * This will usually be a 'path' (hence the name of the method), but can
+	 * be anything that fulfilly the above criterions.
+	 */
 	virtual String path() const;
 
 	/**