mail[Wesnoth-commits] r20191 - in /trunk/src: filesystem.cpp filesystem.hpp


Others Months | Index by Date | Thread Index
>>   [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Header


Content

Posted by gurt on September 08, 2007 - 05:32:
Author: hajo
Date: Sat Sep  8 05:31:35 2007
New Revision: 20191

URL: http://svn.gna.org/viewcvs/wesnoth?rev=20191&view=rev
Log:
doxygen, comments

Modified:
    trunk/src/filesystem.cpp
    trunk/src/filesystem.hpp

Modified: trunk/src/filesystem.cpp
URL: 
http://svn.gna.org/viewcvs/wesnoth/trunk/src/filesystem.cpp?rev=20191&r1=20190&r2=20191&view=diff
==============================================================================
--- trunk/src/filesystem.cpp (original)
+++ trunk/src/filesystem.cpp Sat Sep  8 05:31:35 2007
@@ -12,11 +12,15 @@
    See the COPYING file for more details.
 */
 
+//! @file filesystem.cpp 
+//! File-IO
+
 #include "global.hpp"
 
-//include files for opendir(3), readdir(3), etc. These files may vary
-//from platform to platform, since these functions are NOT ANSI-conforming
-//functions. They may have to be altered to port to new platforms
+// Include files for opendir(3), readdir(3), etc. 
+// These files may vary from platform to platform, 
+// since these functions are NOT ANSI-conforming functions. 
+// They may have to be altered to port to new platforms
 #include <sys/types.h>
 
 //for mkdir
@@ -94,9 +98,7 @@
 {
        char    search_spec[_MAX_PATH +1];
 
-       /* Simply add the *.*, ensuring the path separator is
-        * included.
-        */
+       // Simply add the *.*, ensuring the path separator is included.
        (void)lstrcpyA(search_spec, name);
        if( '\\' != search_spec[lstrlenA(search_spec) - 1] &&
                '/' != search_spec[lstrlenA(search_spec) - 1])
@@ -120,14 +122,14 @@
        DIR     *result =       NULL;
        DWORD   dwAttr;
 
-       /* Must be a valid name */
+       // Must be a valid name 
        if( !name ||
                !*name ||
                (dwAttr = GetFileAttributes(name)) == 0xFFFFFFFF)
        {
                errno = ENOENT;
        }
-       /* Must be a directory */
+       // Must be a directory 
        else if(!(dwAttr & FILE_ATTRIBUTE_DIRECTORY))
        {
                errno = ENOTDIR;
@@ -152,7 +154,7 @@
                        }
                        else
                        {
-                               /* Save the directory, in case of rewind. */
+                               // Save the directory, in case of rewind. 
                                (void)lstrcpyA(result->directory, name);
                                (void)lstrcpyA(result->dirent.d_name, 
result->find_data.cFileName);
                                result->dirent.d_mode   =       
(int)result->find_data.dwFileAttributes;
@@ -175,7 +177,7 @@
        }
        else
        {
-               /* Close the search handle, if not already done. */
+               // Close the search handle, if not already done.
                if(dir->hFind != INVALID_HANDLE_VALUE)
                {
                        (void)FindClose(dir->hFind);
@@ -191,7 +193,7 @@
 
 struct dirent *readdir(DIR *dir)
 {
-       /* The last find exhausted the matches, so return NULL. */
+       // The last find exhausted the matches, so return NULL.
        if(dir->hFind == INVALID_HANDLE_VALUE)
        {
                if(FILE_ATTRIBUTE_ERROR == dir->find_data.dwFileAttributes)
@@ -207,17 +209,13 @@
        }
        else
        {
-               /* Copy the result of the last successful match to
-                * dirent.
-                */
+               // Copy the result of the last successful match to dirent.
                (void)lstrcpyA(dir->dirent.d_name, dir->find_data.cFileName);
 
-               /* Attempt the next match. */
+               // Attempt the next match.
                if(!FindNextFileA(dir->hFind, &dir->find_data))
                {
-                       /* Exhausted all matches, so close and null the
-                        * handle.
-                        */
+                       // Exhausted all matches, so close and null the 
handle.
                        (void)FindClose(dir->hFind);
                        dir->hFind = INVALID_HANDLE_VALUE;
                }
@@ -267,7 +265,7 @@
 BPath be_path;
 #endif
 
-//for getenv
+// for getenv
 #include <cstdlib>
 #include <cerrno>
 #include <cstring>
@@ -315,9 +313,9 @@
                                          FILE_NAME_MODE mode,
                                          FILE_REORDER_OPTION reorder)
 {
-       // if we have a path to find directories in, then
-       // convert relative pathnames to be rooted on the
-       // wesnoth path
+       // If we have a path to find directories in, 
+       // then convert relative pathnames to be rooted 
+       // on the wesnoth path
 #ifndef __AMIGAOS4__
        if(!directory.empty() && directory[0] != '/' && 
!game_config::path.empty()){
                const std::string& dir = game_config::path + "/" + directory;
@@ -365,9 +363,8 @@
                if(entry->d_name[0] == '.')
                        continue;
 #ifdef __APPLE__
-               /* HFS Mac OS X decomposes filenames using combining unicode
-               characters. Try to get the precomposed form.
-               */
+               // HFS Mac OS X decomposes filenames using combining unicode 
characters. 
+               // Try to get the precomposed form.
                char basename[MAXNAMLEN+1];
                CFStringRef cstr = CFStringCreateWithCString(NULL,
                                                         entry->d_name,
@@ -381,7 +378,7 @@
                CFRelease(cstr);
                CFRelease(mut_str);
 #else
-               /* generic Unix */
+               // generic Unix 
                char *basename = entry->d_name;
 #endif /* !APPLE */
 
@@ -417,7 +414,7 @@
                                                        LOG_FS << 
std::string(basename) << "/" << MAINCFG << '\n';
                                        }
                                        } else {
-                                       // show what I consider strange
+                                       // Show what I consider strange
                                                LOG_FS << fullname << "/" << 
MAINCFG << " not used now but skip the directory \n";
                                        }
                                } else if (dirs != NULL) {
@@ -526,8 +523,8 @@
        return (mkdir(path.c_str(),AccessMode) == 0);
 }
 
-//this deletes a directory with no hidden files and subdirectories
-//also deletes a single file
+// This deletes a directory with no hidden files and subdirectories.
+// Also deletes a single file.
 bool delete_directory(const std::string& path)
 {
        bool ret = true;
@@ -648,7 +645,7 @@
        if(dir == NULL) {
                const int res = mkdir(dir_path.c_str(),AccessMode);
 
-               //also create the maps directory
+               // Also create the maps directory
                mkdir((dir_path + "/editor").c_str(),AccessMode);
                mkdir((dir_path + "/editor/maps").c_str(),AccessMode);
                mkdir((dir_path + "/data").c_str(),AccessMode);
@@ -692,9 +689,9 @@
                delete s;
        }
 
-       // FIXME: why do we rely on this even with relative paths ?
-       // still useful with zipios, for things like cache and prefs
-       // NOTE zipios has been removed not sure what to do with this code
+       //! @todo FIXME: why do we rely on this even with relative paths ?
+       // Still useful with zipios, for things like cache and prefs.
+       // NOTE zipios has been removed - not sure what to do with this code.
        std::istream *s = new std::ifstream(fname.c_str(), 
std::ios_base::binary);
        if (s->fail())
                LOG_FS << "streaming " << fname << " failed.\n";
@@ -713,7 +710,7 @@
        return new std::ofstream(fname.c_str(), std::ios_base::binary);
 }
 
-//throws io_exception if an error occurs
+// Throws io_exception if an error occurs
 void write_file(const std::string& fname, const std::string& data)
 {
        //const util::scoped_resource<FILE*,close_FILE> 
file(fopen(fname.c_str(),"wb"));
@@ -805,7 +802,7 @@
 }
 
 std::string next_filename(const std::string &dirname, unsigned int max)
-//return the next ordered full filename within this directory
+// Return the next ordered full filename within this directory
 {
        std::vector<std::string> files;
        std::stringstream fname;
@@ -913,7 +910,7 @@
 }
 
 std::string file_name(const std::string& file)
-// analogous to POSIX basename(3), but for C++ string-object pathnames
+// Analogous to POSIX basename(3), but for C++ string-object pathnames
 {
 #ifdef _WIN32
        static const std::string dir_separators = "\\/:";
@@ -932,7 +929,7 @@
 }
 
 std::string directory_name(const std::string& file)
-// analogous to POSIX dirname(3), but for C++ string-object pathnames
+// Analogous to POSIX dirname(3), but for C++ string-object pathnames
 {
 #ifdef _WIN32
        static const std::string dir_separators = "\\/:";

Modified: trunk/src/filesystem.hpp
URL: 
http://svn.gna.org/viewcvs/wesnoth/trunk/src/filesystem.hpp?rev=20191&r1=20190&r2=20191&view=diff
==============================================================================
--- trunk/src/filesystem.hpp (original)
+++ trunk/src/filesystem.hpp Sat Sep  8 05:31:35 2007
@@ -11,6 +11,10 @@
 
    See the COPYING file for more details.
 */
+
+//! @file filesystem.hpp 
+//! Declarations for File-IO.
+
 #ifndef FILESYSTEM_HPP_INCLUDED
 #define FILESYSTEM_HPP_INCLUDED
 
@@ -20,7 +24,7 @@
 #include <string>
 #include <vector>
 
-//an exception object used when an IO error occurs
+//! An exception object used when an IO error occurs
 struct io_exception : public std::exception {
        io_exception() : message("") {}
        io_exception(const std::string& msg) : message(msg) {}
@@ -34,12 +38,11 @@
 enum FILE_NAME_MODE { ENTIRE_FILE_PATH, FILE_NAME_ONLY };
 enum FILE_REORDER_OPTION { DONT_REORDER, DO_REORDER };
 
-//function which populates files with all the files and dirs
-//with all the directories in dir. If files or dirs are NULL
-//they will not be used.
-//
-//mode determines whether the entire path or just the filename
-//is retrieved.
+//! Populates 'files' with all the files and 
+//! 'dirs' with all the directories in dir. 
+//! If files or dirs are NULL they will not be used.
+//!
+//! Mode determines whether the entire path or just the filename is 
retrieved.
 void get_files_in_dir(const std::string& dir,
                       std::vector<std::string>* files,
                       std::vector<std::string>* dirs=NULL,
@@ -47,7 +50,8 @@
                       FILE_REORDER_OPTION reorder=DONT_REORDER);
 
 std::string get_dir(const std::string &dir);
-//the location of various important files
+
+// The location of various important files:
 std::string get_prefs_file();
 std::string get_save_index_file();
 std::string get_saves_dir();
@@ -62,25 +66,27 @@
 bool make_directory(const std::string& dirname);
 bool delete_directory(const std::string& dirname);
 
-//basic disk I/O
+// Basic disk I/O:
+
+//! Basic disk I/O - read file.
 std::string read_file(const std::string& fname);
 std::istream *istream_file(std::string const &fname);
 std::ostream *ostream_file(std::string const &fname);
-//throws io_exception if an error occurs
+//! Throws io_exception if an error occurs.
 void write_file(const std::string& fname, const std::string& data);
 
 std::string read_map(const std::string& name);
 
-//function which returns true iff the given file is a directory
+//! Returns true iff the given file is a directory.
 bool is_directory(const std::string& fname);
 
-//function which returns true iff file with name already exists
+//! Returns true iff file with name already exists.
 bool file_exists(const std::string& name);
 
-//function to get the creation time of a file
+//! Get the creation time of a file.
 time_t file_create_time(const std::string& fname);
 
-//return the next ordered full filename within this directory
+//! Return the next ordered full filename within this directory.
 std::string next_filename(const std::string &dirname, unsigned int max = 0);
 
 struct file_tree_checksum
@@ -96,27 +102,31 @@
 bool operator!=(const file_tree_checksum& lhs, const file_tree_checksum& 
rhs);
 
 
-//function to get the time at which the data/ tree was last modified at
+//! Get the time at which the data/ tree was last modified at.
 const file_tree_checksum& data_tree_checksum();
 
-//returns the size of a file, or -1 if the file doesn't exist
+//! Returns the size of a file, or -1 if the file doesn't exist.
 int file_size(const std::string& fname);
 
-//returns the base filename of a file, with directory name stripped. 
Equivalent
-//to a portable basename() function
+//! Returns the base filename of a file, with directory name stripped. 
+//! Equivalent to a portable basename() function.
 std::string file_name(const std::string& file);
 
-//returns the directory name of a file, with filename stripped. Equivalent 
to a
-//portable dirname()
+//! Returns the directory name of a file, with filename stripped. 
+//! Equivalent to a portable dirname()
 std::string directory_name(const std::string& file);
 
-///the paths manager is responsible for recording the various paths that
-///binary files may be located at. It should be passed a config object
-///which holds binary path information. This is in the format
-///[binary_path]
-///path=<path>
-///[/binary_path]
-///Binaries will be searched for in [wesnoth-path]/data/<path>/images/
+/*! The paths manager is responsible for recording the various paths 
+ *  that binary files may be located at. 
+ *  It should be passed a config object which holds binary path information. 
+ *  This is in the format
+ *@verbatim
+ *    [binary_path]
+ *      path=<path>
+ *    [/binary_path]
+ *  Binaries will be searched for in [wesnoth-path]/data/<path>/images/
+ *@endverbatim
+ */
 struct binary_paths_manager
 {
        binary_paths_manager();
@@ -136,13 +146,12 @@
 
 void clear_binary_paths_cache();
 
-//function which, given a type of binary, e.g. 'images', 'sounds', etc,
-//will return a vector with all possible paths to that type of binary
+//! Returns a vector with all possible paths to a given type of binary,
+//! e.g. 'images', 'sounds', etc,
 const std::vector<std::string>& get_binary_paths(const std::string& type);
 
-//function which, given a type of binary, and the name of the binary file,
-//will return a complete path to the actual file, or an empty string if
-//the file isn't present
+//! Returns a complete path to the actual file of a given a type of binary, 
+//! or an empty string if the file isn't present.
 std::string get_binary_file_location(const std::string& type, const 
std::string& filename);
 
 class scoped_istream {




Related Messages


Powered by MHonArc, Updated Sat Sep 08 08:01:03 2007