diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2022-04-26 14:49:28 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-04-26 16:49:28 -0500 |
commit | 72628c1ccc5e7d85fe297312d740eed929ab78bb (patch) | |
tree | 749cb14609827a540e6189a2ee6ed73bb9129a5a /file.c | |
parent | a8541475d1339ce242357822dd49d775645ce76d (diff) |
Enhanced RDoc for File (#5849)
Treats:
#path
::stat
::lstat
#lstat
::directory?
Also adds section "Example Files" that explains assumptions about example files. I'm using t.txt already, and I'm pretty sure I'll need t.dat (binary data). I don't know whether I'll need t.rus (Russian text).
Notes
Notes:
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
Diffstat (limited to 'file.c')
-rw-r--r-- | file.c | 102 |
1 files changed, 67 insertions, 35 deletions
@@ -444,21 +444,21 @@ apply2files(int (*func)(const char *, void *), int argc, VALUE *argv, void *arg) /* * call-seq: - * file.path -> filename - * file.to_path -> filename + * path -> filepath * - * Returns the pathname used to create <i>file</i> as a string. Does - * not normalize the name. + * Returns the string filepath used to create +self+: * - * The pathname may not point to the file corresponding to <i>file</i>. - * For instance, the pathname becomes void when the file has been - * moved or deleted. + * f = File.new('t.txt') # => #<File:t.txt> + f.path # => "t.txt" * - * This method raises IOError for a <i>file</i> created using - * File::Constants::TMPFILE because they don't have a pathname. + * Does not normalize the returned filepath: * - * File.new("testfile").path #=> "testfile" - * File.new("/tmp/../tmp/xxx", "w").path #=> "/tmp/../tmp/xxx" + * f = File.new('../files/t.txt') # => #<File:../files/t.txt> + f.path # => "../files/t.txt" + * + * Raises IOError for a file created using File::Constants::TMPFILE, because it has no filename. + * + * File#to_path is an alias for File#path. * */ @@ -1309,11 +1309,11 @@ rb_stat(VALUE file, struct stat *st) /* * call-seq: - * File.stat(file_name) -> stat + * File.stat(filepath) -> stat * - * Returns a File::Stat object for the named file (see File::Stat). + * Returns a File::Stat object for the file at +filepath+ (see File::Stat): * - * File.stat("testfile").mtime #=> Tue Apr 08 12:58:04 CDT 2003 + * File.stat('t.txt').class # => File::Stat * */ @@ -1381,15 +1381,14 @@ lstat_without_gvl(const char *path, struct stat *st) /* * call-seq: - * File.lstat(file_name) -> stat + * File.lstat(filepath) -> stat * - * Same as File::stat, but does not follow the last symbolic link. - * Instead, reports on the link itself. + * Like File::stat, but does not follow the last symbolic link; + * instead, returns a File::Stat object for the link itself. * - * File.symlink("testfile", "link2test") #=> 0 - * File.stat("testfile").size #=> 66 - * File.lstat("link2test").size #=> 8 - * File.stat("link2test").size #=> 66 + * File.symlink('t.txt', 'symlink') + * File.stat('symlink').size # => 47 + * File.lstat('symlink').size # => 5 * */ @@ -1412,16 +1411,16 @@ rb_file_s_lstat(VALUE klass, VALUE fname) /* * call-seq: - * file.lstat -> stat + * lstat -> stat * - * Same as IO#stat, but does not follow the last symbolic link. - * Instead, reports on the link itself. + * Like File#stat, but does not follow the last symbolic link; + * instead, returns a File::Stat object for the link itself: + * + * File.symlink('t.txt', 'symlink') + * f = File.new('symlink') + * f.stat.size # => 47 + * f.lstat.size # => 11 * - * File.symlink("testfile", "link2test") #=> 0 - * File.stat("testfile").size #=> 66 - * f = File.new("link2test") - * f.lstat.size #=> 8 - * f.stat.size #=> 66 */ static VALUE @@ -1590,15 +1589,20 @@ rb_access(VALUE fname, int mode) * Document-method: directory? * * call-seq: - * File.directory?(file_name) -> true or false + * File.directory?(path) -> true or false * - * Returns <code>true</code> if the named file is a directory, - * or a symlink that points at a directory, and <code>false</code> - * otherwise. + * With string +object+ given, returns +true+ if +path+ is a string path + * leading to a directory, or to a symbolic link to a directory; +false+ otherwise: * - * _file_name_ can be an IO object. + * File.directory?('.') # => true + * File.directory?('foo') # => false + * File.symlink('.', 'dirlink') # => 0 + * File.directory?('dirlink') # => true + * File.symlink('t,txt', 'filelink') # => 0 + * File.directory?('filelink') # => false + * + * Argument +path+ can be an IO object. * - * File.directory?(".") */ VALUE @@ -6573,6 +6577,34 @@ const char ruby_null_device[] = * may be found in module File::Constants; * an array of their names is returned by <tt>File::Constants.constants</tt>. * + * == Example Files + * + * Many examples here use these filenames and their corresponding files: + * + * - <tt>t.txt</tt>: A text-only file that is assumed to exist via: + * + * text = <<~EOT + * First line + * Second line + * + * Fourth line + * Fifth line + * EOT + * File.write('t.txt', text) + * + * - <tt>t.dat</tt>: A data file that is assumed to exist via: + * + * data = "\u9990\u9991\u9992\u9993\u9994" + * f = File.open('t.dat', 'wb:UTF-16') + * f.write(data) + * f.close + * + * - <tt>t.rus</tt>: A Russian-language text file that is assumed to exist via: + * + * File.write('t.rus', "\u{442 435 441 442}") + * + * - <tt>t.tmp</tt>: A file that is assumed _not_ to exist. + * * == What's Here * * First, what's elsewhere. \Class \File: |