documented sys.FileSystem and sys.io.File

std/haxe/io/Path.hx

@@ -24,8 +24,9 @@ package haxe.io;
 /**
 	This class provides a convenient way of working with paths. It supports the
 	common path formats:
-		directory1/directory2/filename.extension
-		directory1\directory2\filename.excention
+		
+	- directory1/directory2/filename.extension
+	- directory1\directory2\filename.excention
 **/
 class Path {
 
@@ -67,7 +68,7 @@ class Path {
 	public var backslash : Bool;
 
 	/**
-		Creates a new Path instance by parsing [path].
+		Creates a new Path instance by parsing `path`.
 		
 		Path information can be retrieved by accessing the dir, file and ext
 		properties.
@@ -95,13 +96,13 @@ class Path {
 	}
 
 	/**
-		Returns a String representation of [this] path.
+		Returns a String representation of `this` path.
 		
-		If [this].backslash is true, backslash is used as directory separator,
+		If `this.backslash` is true, backslash is used as directory separator,
 		otherwise slash is used. This only affects the separator between
-		[this].dir and [this].file.
+		`this.dir` and `this.file`.
 		
-		If [this].directory or [this].extension is null, their representation
+		If `this.directory` or `this.extension` is null, their representation
 		is the empty String "".
 	**/
 	public function toString() {
@@ -109,9 +110,9 @@ class Path {
 	}
 
 	/**
-		Returns the String representation of [path] without the file extension.
+		Returns the String representation of `path` without the file extension.
 		
-		If [path] is null, the result is unspecified.
+		If `path` is null, the result is unspecified.
 	**/
 	public static function withoutExtension( path : String ) {
 		var s = new Path(path);
@@ -120,9 +121,9 @@ class Path {
 	}
 
 	/**
-		Returns the String representation of [path] without the directory.
+		Returns the String representation of `path` without the directory.
 		
-		If [path] is null, the result is unspecified.
+		If `path` is null, the result is unspecified.
 	**/
 	public static function withoutDirectory( path ) {
 		var s = new Path(path);
@@ -131,11 +132,11 @@ class Path {
 	}
 
 	/**
-		Returns the directory of [path].
+		Returns the directory of `path`.
 		
 		If the directory is null, the empty String "" is returned.
 		
-		If [path] is null, the result is unspecified.
+		If `path` is null, the result is unspecified.
 	**/
 	public static function directory( path ) {
 		var s = new Path(path);
@@ -145,11 +146,11 @@ class Path {
 	}
 
 	/**
-		Returns the extension of [path].
+		Returns the extension of `path`.
 		
 		If the extension is null, the empty String "" is returned.
 		
-		If [path] is null, the result is unspecified.
+		If `path` is null, the result is unspecified.
 	**/
 	public static function extension( path ) {
 		var s = new Path(path);
@@ -159,11 +160,11 @@ class Path {
 	}
 
 	/**
-		Returns a String representation of [path] where the extension is [ext].
+		Returns a String representation of `path` where the extension is `ext`.
 		
-		If [path] has no extension, [ext] is added as extension.
+		If `path` has no extension, `ext` is added as extension.
 		
-		If [path] or [ext] are null, the result is unspecified.
+		If `path` or `ext` are null, the result is unspecified.
 	**/
 	public static function withExtension( path, ext ) {
 		var s = new Path(path);
@@ -172,16 +173,16 @@ class Path {
 	}
 
 	/**
-		Adds a trailing slash to [path], if it does not have one already.
+		Adds a trailing slash to `path`, if it does not have one already.
 		
-		If the last slash in [path] is a backslash, a backslash is appended to
-		[path].
+		If the last slash in `path` is a backslash, a backslash is appended to
+		`path`.
 		
-		If the last slash in [path] is a slash, or if no slash is found, a slash
-		is appended to [path]. In particular, this applies to the empty String
+		If the last slash in `path` is a slash, or if no slash is found, a slash
+		is appended to `path`. In particular, this applies to the empty String
 		"".
 		
-		If [path] is null, the result is unspecified.
+		If `path` is null, the result is unspecified.
 	**/
 	public static function addTrailingSlash( path : String ) : String {
 		if (path.length == 0)

std/sys/FileSystem.hx

@@ -22,51 +22,93 @@
 package sys;
 
 /**
-	This class allows you to get informations about the files and directories.
+	This class allows you to get information about the files and directories.
+	
+	See `sys.io.File` for the complementary file API.
 **/
 extern class FileSystem {
 
 	/**
-		Tells if the given file or directory exists.
+		Tells if the file or directory specified by `path` exists.
+		
+		If `path` is null, the result is unspecified.
 	**/
 	static function exists( path : String ) : Bool;
 
 	/**
-		Rename the corresponding file or directory, allow to move it accross directories as well.
+		Renames/moves the file or directory specified by `path` to `newPath`.
+		
+		If `path` is not a valid file system entry, or if it is not accessible,
+		or if `newPath` is not accessible, an exception is thrown.
+		
+		If `path` or `newPath` are null, the result is unspecified.
 	**/
-	static function rename( path : String, newpath : String ) : Void;
+	static function rename( path : String, newPath : String ) : Void;
 
 	/**
-		Returns informations for the given file/directory.
+		Returns `FileStat` information on the file or directory specified by
+		`path`.
+		
+		If `path` is null, the result is unspecified.
 	**/
 	static function stat( path : String ) : FileStat;
 
 	/**
-		Returns the full path for the given path which is relative to the current working directory.
+		Returns the full path of the file or directory specified by `relPath`,
+		which is relative to the current working directory.
+		
+		If `relPath` is null, the result is unspecified.
 	**/
-	static function fullPath( relpath : String ) : String;
+	static function fullPath( relPath : String ) : String;
 
 	/**
-		Tells if the given path is a directory. Throw an exception if it does not exists or is not accesible.
+		Tells if the file or directory specified by `path` is a directory.
+		
+		If `path` is not a valid file system entry or if its destination is no
+		accessible, an exception is thrown.
+		
+		If `path` is null, the result is unspecified.
 	**/
 	static function isDirectory( path : String ) : Bool;
 
-	/**
-		Create the given directory. Not recursive : the parent directory must exists.
+	/**	
+		Creates a directory specified by `path`.
+		
+		This method is not recursive: All parent directories must exist.
+		
+		If the directory cannot be created, an exception is thrown.
+		
+		If `path` is null, the result is unspecified.
 	**/
 	static function createDirectory( path : String ) : Void;
 
 	/**
-		Delete a given file.
+		Deletes the file specified by `path`.
+		
+		If `path` does not denote a valid file, or if that file cannot be
+		deleted, an exception is thrown.
+		
+		If `path` is null, the result is unspecified.
 	**/
 	static function deleteFile( path : String ) : Void;
+	
 	/**
-		Delete a given directory.
+		Deletes the directory specified by `path`.
+		
+		If `path` does not denote a valid directory, or if that directory cannot
+		be deleted, an exception is thrown.
+		
+		If `path` is null, the result is unspecified.
 	**/
 	static function deleteDirectory( path : String ) : Void;
 
 	/**
-		Read all the files/directories stored into the given directory.
+		Returns the names of all files and directory in the directory specified
+		by `path`.
+		
+		If `path` does not denote a valid directory, an exception is thrown.
+		
+		If `path` is null, the result is unspecified.
 	**/
 	static function readDirectory( path : String ) : Array<String>;
 

std/sys/io/File.hx

@@ -23,15 +23,103 @@ package sys.io;
 
 /**
 	API for reading and writing to files.
+	
+	See `sys.FileSystem` for the complementary file system API.
 **/
 extern class File {
 
+	/**
+		Retrieves the content of the file specified by `path` as a String.
+		
+		If the file does not exist or can not be read, an exception is thrown.
+		
+		`sys.FileSystem.exists` can be used to check for existence.
+		
+		If `path` is null, the result is unspecified.
+	**/
 	static function getContent( path : String ) : String;
+	
+	/**
+		Stores `content` in the file specified by `path`.
+		
+		If the file cannot be written to, an exception is thrown.
+		
+		If `path` or `content` are null, the result is unspecified.
+	**/
 	static function saveContent( path : String, content : String ) : Void;
+	
+	/**
+		Retrieves the binary content of the file specified by `path`.
+		
+		If the file does not exist or can not be read, an exception is thrown.
+		
+		`sys.FileSystem.exists` can be used to check for existence.
+		
+		If `path` is null, the result is unspecified.
+	**/	
 	static function getBytes( path : String ) : haxe.io.Bytes;
+	
+	/**
+		Stores `bytes` in the file specified by `path` in binary mode.
+		
+		If the file cannot be written to, an exception is thrown.
+		
+		If `path` or `bytes` are null, the result is unspecified.
+	**/	
 	static function saveBytes( path : String, bytes : haxe.io.Bytes ) : Void;
+	
+	/**
+		Returns an `FileInput` handle to the file specified by `path`.
+		
+		If `binary` is true, the file is opened in binary mode. Otherwise it is
+		opened in non-binary mode.
+		
+		If the file does not exist or can not be read, an exception is thrown.
+		
+		Operations on the returned `FileInput` handle read on the opened file.
+		
+		File handles should be closed via `FileInput.close` once the operation
+		is complete.
+		
+		If `path` is null, the result is unspecified.
+	**/
 	static function read( path : String, binary : Bool = true ) : FileInput;
+	
+	/**
+		Returns an `FileOutput` handle to the file specified by `path`.
+		
+		If `binary` is true, the file is opened in binary mode. Otherwise it is
+		opened in non-binary mode.
+		
+		If the file cannot be written to, an exception is thrown.
+		
+		Operations on the returned `FileOutput` handle write to the opened file.
+		If the file existed, its previous content is overwritten.
+		
+		File handles should be closed via `FileOutput.close` once the operation
+		is complete.
+		
+		If `path` is null, the result is unspecified.
+	**/	
 	static function write( path : String, binary : Bool = true ) : FileOutput;
+	
+	/**
+		Similar to `sys.io.File.write`, but appends to the file if it exists
+		instead of overwriting its contents.
+	**/
 	static function append( path : String, binary : Bool = true ) : FileOutput;
-	static function copy( src : String, dst : String ) : Void;
+	
+	
+	/**
+		Copies the contents of the file specified by `srcPath` to the file
+		specified by `dstPath`.
+		
+		If the `srcPath` does not exist or cannot be read, or if the `dstPath`
+		file cannot be written to, an exception is thrown.
+		
+		If the file at `dstPath` exists, its contents are overwritten.
+		
+		If `srcPath` or `dstPath` are null, the result is unspecified.
+	**/
+	static function copy( srcPath : String, dstPath : String ) : Void;
 }