Skip to content

Commit dcbad90

Browse files
BurdetteLamarBurdetteLamar
authored
[DOC] Revisions for module-level doc (#90)
* Revisions for module-level doc
1 parent 13ab964 commit dcbad90

File tree

1 file changed

+80
-90
lines changed

1 file changed

+80
-90
lines changed

‎lib/fileutils.rb‎

Lines changed: 80 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,90 @@
66
# for make mjit-headers
77
end
88

9+
# Namespace for file utility methods for copying, moving, removing, etc.
910
#
10-
# = fileutils.rb
11+
# == What's Here
1112
#
12-
# Copyright (c) 2000-2007 Minero Aoki
13+
# First, what’s elsewhere. \Module \FileUtils:
1314
#
14-
# This program is free software.
15-
# You can distribute/modify this program under the same terms of ruby.
15+
# - Inherits from {class Object}[https://docs.ruby-lang.org/en/master/Object.html].
16+
# - Supplements {class File}[https://docs.ruby-lang.org/en/master/File.html]
17+
# (but is not included or extended there).
1618
#
17-
# == module FileUtils
19+
# Here, module \FileUtils provides methods that are useful for:
1820
#
19-
# Namespace for several file utility methods for copying, moving, removing, etc.
21+
# - {Creating}[rdoc-ref:FileUtils@Creating].
22+
# - {Deleting}[rdoc-ref:FileUtils@Deleting].
23+
# - {Querying}[rdoc-ref:FileUtils@Querying].
24+
# - {Setting}[rdoc-ref:FileUtils@Setting].
25+
# - {Comparing}[rdoc-ref:FileUtils@Comparing].
26+
# - {Copying}[rdoc-ref:FileUtils@Copying].
27+
# - {Moving}[rdoc-ref:FileUtils@Copying].
28+
# - {Options}[rdoc-ref:FileUtils@Options].
29+
#
30+
# === Creating
31+
#
32+
# - ::mkdir: Creates directories.
33+
# - ::mkdir_p, ::makedirs, ::mkpath: Creates directories,
34+
# also creating ancestor directories as needed.
35+
# - ::link_entry: Creates a hard link.
36+
# - ::ln, ::link: Creates hard links.
37+
# - ::ln_s, ::symlink: Creates symbolic links.
38+
# - ::ln_sf: Creates symbolic links, overwriting if necessary.
39+
#
40+
# === Deleting
41+
#
42+
# - ::remove_dir: Removes a directory and its descendants.
43+
# - ::remove_entry: Removes an entry, including its descendants if it is a directory.
44+
# - ::remove_entry_secure: Like ::remove_entry, but removes securely.
45+
# - ::remove_file: Removes a file entry.
46+
# - ::rm, ::remove: Removes entries.
47+
# - ::rm_f, ::safe_unlink: Like ::rm, but removes forcibly.
48+
# - ::rm_r: Removes entries and their descendants.
49+
# - ::rm_rf, ::rmtree: Like ::rm_r, but removes forcibly.
50+
# - ::rmdir: Removes directories.
51+
#
52+
# === Querying
53+
#
54+
# - ::pwd, ::getwd: Returns the path to the working directory.
55+
# - ::uptodate?: Returns whether a given entry is newer than given other entries.
56+
#
57+
# === Setting
58+
#
59+
# - ::cd, ::chdir: Sets the working directory.
60+
# - ::chmod: Sets permissions for an entry.
61+
# - ::chmod_R: Sets permissions for an entry and its descendants.
62+
# - ::chown: Sets the owner and group for entries.
63+
# - ::chown_R: Sets the owner and group for entries and their descendants.
64+
# - ::touch: Sets modification and access times for entries,
65+
# creating if necessary.
66+
#
67+
# === Comparing
68+
#
69+
# - ::compare_file, ::cmp, ::identical?: Returns whether two entries are identical.
70+
# - ::compare_stream: Returns whether two streams are identical.
71+
#
72+
# === Copying
73+
#
74+
# - ::copy_entry: Recursively copies an entry.
75+
# - ::copy_file: Copies an entry.
76+
# - ::copy_stream: Copies a stream.
77+
# - ::cp, ::copy: Copies files.
78+
# - ::cp_lr: Recursively creates hard links.
79+
# - ::cp_r: Recursively copies files.
80+
# - ::install: Recursively copies files (with options different from ::cp_r).
81+
#
82+
# === Moving
83+
#
84+
# - ::mv, ::move: Moves entries.
85+
#
86+
# === Options
87+
#
88+
# - ::collect_method: Returns the names of methods that accept a given option.
89+
# - ::commands: Returns the names of methods that accept options.
90+
# - ::have_option?: Returns whether a given method accepts a given option.
91+
# - ::options: Returns all option names.
92+
# - ::options_of: Returns the names of the options for a given method.
2093
#
2194
# == Path Arguments
2295
#
@@ -59,89 +132,6 @@
59132
# |-- find_executable.rb
60133
# `-- helper.rb
61134
#
62-
# === Module Functions
63-
#
64-
# require 'fileutils'
65-
#
66-
# FileUtils.cd(dir, **options)
67-
# FileUtils.cd(dir, **options) {|dir| block }
68-
# FileUtils.pwd()
69-
# FileUtils.mkdir(dir, **options)
70-
# FileUtils.mkdir(list, **options)
71-
# FileUtils.mkdir_p(dir, **options)
72-
# FileUtils.mkdir_p(list, **options)
73-
# FileUtils.rmdir(dir, **options)
74-
# FileUtils.rmdir(list, **options)
75-
# FileUtils.ln(target, link, **options)
76-
# FileUtils.ln(targets, dir, **options)
77-
# FileUtils.ln_s(target, link, **options)
78-
# FileUtils.ln_s(targets, dir, **options)
79-
# FileUtils.ln_sf(target, link, **options)
80-
# FileUtils.cp(src, dest, **options)
81-
# FileUtils.cp(list, dir, **options)
82-
# FileUtils.cp_r(src, dest, **options)
83-
# FileUtils.cp_r(list, dir, **options)
84-
# FileUtils.mv(src, dest, **options)
85-
# FileUtils.mv(list, dir, **options)
86-
# FileUtils.rm(list, **options)
87-
# FileUtils.rm_r(list, **options)
88-
# FileUtils.rm_rf(list, **options)
89-
# FileUtils.install(src, dest, **options)
90-
# FileUtils.chmod(mode, list, **options)
91-
# FileUtils.chmod_R(mode, list, **options)
92-
# FileUtils.chown(user, group, list, **options)
93-
# FileUtils.chown_R(user, group, list, **options)
94-
# FileUtils.touch(list, **options)
95-
#
96-
# Possible <tt>options</tt> are:
97-
#
98-
# <tt>:force</tt> :: forced operation (rewrite files if exist, remove
99-
# directories if not empty, etc.);
100-
# <tt>:verbose</tt> :: print command to be run, in bash syntax, before
101-
# performing it;
102-
# <tt>:preserve</tt> :: preserve object's group, user and modification
103-
# time on copying;
104-
# <tt>:noop</tt> :: no changes are made (usable in combination with
105-
# <tt>:verbose</tt> which will print the command to run)
106-
#
107-
# Each method documents the options that it honours. See also ::commands,
108-
# ::options and ::options_of methods to introspect which command have which
109-
# options.
110-
#
111-
# All methods that have the concept of a "source" file or directory can take
112-
# either one file or a list of files in that argument. See the method
113-
# documentation for examples.
114-
#
115-
# There are some `low level' methods, which do not accept keyword arguments:
116-
#
117-
# FileUtils.copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
118-
# FileUtils.copy_file(src, dest, preserve = false, dereference = true)
119-
# FileUtils.copy_stream(srcstream, deststream)
120-
# FileUtils.remove_entry(path, force = false)
121-
# FileUtils.remove_entry_secure(path, force = false)
122-
# FileUtils.remove_file(path, force = false)
123-
# FileUtils.compare_file(path_a, path_b)
124-
# FileUtils.compare_stream(stream_a, stream_b)
125-
# FileUtils.uptodate?(file, cmp_list)
126-
#
127-
# == module FileUtils::Verbose
128-
#
129-
# This module has all methods of FileUtils module, but it outputs messages
130-
# before acting. This equates to passing the <tt>:verbose</tt> flag to methods
131-
# in FileUtils.
132-
#
133-
# == module FileUtils::NoWrite
134-
#
135-
# This module has all methods of FileUtils module, but never changes
136-
# files/directories. This equates to passing the <tt>:noop</tt> flag to methods
137-
# in FileUtils.
138-
#
139-
# == module FileUtils::DryRun
140-
#
141-
# This module has all methods of FileUtils module, but never changes
142-
# files/directories. This equates to passing the <tt>:noop</tt> and
143-
# <tt>:verbose</tt> flags to methods in FileUtils.
144-
#
145135
# == Avoiding the TOCTTOU Vulnerability
146136
#
147137
# For certain methods that recursively remove entries,
@@ -2411,7 +2401,7 @@ def fu_output_message(msg) #:nodoc:
24112401
public
24122402

24132403
# Returns an array of the string names of \FileUtils methods
2414-
# that accept one or more keyword arguments;
2404+
# that accept one or more keyword arguments:
24152405
#
24162406
# FileUtils.commands.sort.take(3) # => ["cd", "chdir", "chmod"]
24172407
#

0 commit comments

Comments
 (0)