Small doc touchups and doctests for mv (#28032)

* Small doc touchups and doctests for mv

* Remove extraneous doctest stuff

base/essentials.jl

@@ -774,8 +774,8 @@ function peek end
 """
  @__LINE__ -> Int
 
-`@__LINE__` expands to the line number of the location of the macrocall.
-Returns `0` if the line number could not be determined.
+Expand to the line number of the location of the macrocall.
+Return `0` if the line number could not be determined.
 """
 macro __LINE__()
  return __source__.line

base/file.jl

@@ -103,7 +103,7 @@ end
 """
  cd(f::Function, dir::AbstractString=homedir())
 
-Temporarily change the current working directory, apply function `f` and
+Temporarily change the current working directory to `dir`, apply function `f` and
 finally return to the original directory.
 
 # Examples
@@ -358,6 +358,32 @@ end
 Move the file, link, or directory from `src` to `dst`.
 `force=true` will first remove an existing `dst`.
 Return `dst`.
+
+# Examples
+```jldoctest; filter = r"Stacktrace:(\\n \\[[0-9]+\\].*)*"
+julia> write("hello.txt", "world");
+
+julia> mv("hello.txt", "goodbye.txt")
+"goodbye.txt"
+
+julia> "hello.txt" in readdir()
+false
+
+julia> readline("goodbye.txt")
+"world"
+
+julia> write("hello.txt", "world2");
+
+julia> mv("hello.txt", "goodbye.txt")
+ERROR: ArgumentError: 'goodbye.txt' exists. `force=true` is required to remove 'goodbye.txt' before moving.
+Stacktrace:
+ [1] #checkfor_mv_cp_cptree#10(::Bool, ::Function, ::String, ::String, ::String) at ./file.jl:293
+[...]
+
+julia> mv("hello.txt", "goodbye.txt", force=true)
+"goodbye.txt"
+
+```
 """
 function mv(src::AbstractString, dst::AbstractString; force::Bool=false,
  remove_destination::Union{Bool,Nothing}=nothing)

base/loading.jl

@@ -1391,9 +1391,9 @@ end
 """
  @__FILE__ -> AbstractString
 
-`@__FILE__` expands to a string with the path to the file containing the
+Expand to a string with the path to the file containing the
 macrocall, or an empty string if evaluated by `julia -e <expr>`.
-Returns `nothing` if the macro was missing parser source information.
+Return `nothing` if the macro was missing parser source information.
 Alternatively see [`PROGRAM_FILE`](@ref).
 """
 macro __FILE__()
@@ -1404,9 +1404,9 @@ end
 """
  @__DIR__ -> AbstractString
 
-`@__DIR__` expands to a string with the absolute path to the directory of the file
+Expand to a string with the absolute path to the directory of the file
 containing the macrocall.
-Returns the current working directory if run from a REPL or if evaluated by `julia -e <expr>`.
+Return the current working directory if run from a REPL or if evaluated by `julia -e <expr>`.
 """
 macro __DIR__()
  __source__.file === nothing && return nothing

base/path.jl

@@ -87,7 +87,7 @@ end
 """
  isabspath(path::AbstractString) -> Bool
 
-Determines whether a path is absolute (begins at the root directory).
+Determine whether a path is absolute (begins at the root directory).
 
 # Examples
 ```jldoctest
@@ -103,7 +103,7 @@ isabspath(path::AbstractString)
 """
  isdirpath(path::AbstractString) -> Bool
 
-Determines whether a path refers to a directory (for example, ends with a path separator).
+Determine whether a path refers to a directory (for example, ends with a path separator).
 
 # Examples
 ```jldoctest

base/stat.jl

@@ -121,7 +121,7 @@ lstat(path...) = lstat(joinpath(path...))
 """
  filemode(file)
 
-Equivalent to `stat(file).mode`
+Equivalent to `stat(file).mode`.
 """
 filemode(st::StatStruct) = st.mode
 
@@ -142,7 +142,7 @@ mtime(st::StatStruct) = st.mtime
 """
  ctime(file)
 
-Equivalent to `stat(file).ctime`
+Equivalent to `stat(file).ctime`.
 """
 ctime(st::StatStruct) = st.ctime
 
@@ -151,28 +151,28 @@ ctime(st::StatStruct) = st.ctime
 """
  ispath(path) -> Bool
 
-Returns `true` if `path` is a valid filesystem path, `false` otherwise.
+Return `true` if `path` is a valid filesystem path, `false` otherwise.
 """
 ispath(st::StatStruct) = filemode(st) & 0xf000 != 0x0000
 
 """
  isfifo(path) -> Bool
 
-Returns `true` if `path` is a FIFO, `false` otherwise.
+Return `true` if `path` is a FIFO, `false` otherwise.
 """
 isfifo(st::StatStruct) = filemode(st) & 0xf000 == 0x1000
 
 """
  ischardev(path) -> Bool
 
-Returns `true` if `path` is a character device, `false` otherwise.
+Return `true` if `path` is a character device, `false` otherwise.
 """
 ischardev(st::StatStruct) = filemode(st) & 0xf000 == 0x2000
 
 """
  isdir(path) -> Bool
 
-Returns `true` if `path` is a directory, `false` otherwise.
+Return `true` if `path` is a directory, `false` otherwise.
 
 # Examples
 ```jldoctest
@@ -188,14 +188,14 @@ isdir(st::StatStruct) = filemode(st) & 0xf000 == 0x4000
 """
  isblockdev(path) -> Bool
 
-Returns `true` if `path` is a block device, `false` otherwise.
+Return `true` if `path` is a block device, `false` otherwise.
 """
 isblockdev(st::StatStruct) = filemode(st) & 0xf000 == 0x6000
 
 """
  isfile(path) -> Bool
 
-Returns `true` if `path` is a regular file, `false` otherwise.
+Return `true` if `path` is a regular file, `false` otherwise.
 
 # Examples
 ```jldoctest
@@ -215,14 +215,14 @@ isfile(st::StatStruct) = filemode(st) & 0xf000 == 0x8000
 """
  islink(path) -> Bool
 
-Returns `true` if `path` is a symbolic link, `false` otherwise.
+Return `true` if `path` is a symbolic link, `false` otherwise.
 """
 islink(st::StatStruct) = filemode(st) & 0xf000 == 0xa000
 
 """
  issocket(path) -> Bool
 
-Returns `true` if `path` is a socket, `false` otherwise.
+Return `true` if `path` is a socket, `false` otherwise.
 """
 issocket(st::StatStruct) = filemode(st) & 0xf000 == 0xc000
 
@@ -231,28 +231,28 @@ issocket(st::StatStruct) = filemode(st) & 0xf000 == 0xc000
 """
  issetuid(path) -> Bool
 
-Returns `true` if `path` has the setuid flag set, `false` otherwise.
+Return `true` if `path` has the setuid flag set, `false` otherwise.
 """
 issetuid(st::StatStruct) = (filemode(st) & 0o4000) > 0
 
 """
  issetgid(path) -> Bool
 
-Returns `true` if `path` has the setgid flag set, `false` otherwise.
+Return `true` if `path` has the setgid flag set, `false` otherwise.
 """
 issetgid(st::StatStruct) = (filemode(st) & 0o2000) > 0
 
 """
  issticky(path) -> Bool
 
-Returns `true` if `path` has the sticky bit set, `false` otherwise.
+Return `true` if `path` has the sticky bit set, `false` otherwise.
 """
 issticky(st::StatStruct) = (filemode(st) & 0o1000) > 0
 
 """
  uperm(file)
 
-Gets the permissions of the owner of the file as a bitfield of
+Get the permissions of the owner of the file as a bitfield of
 
 | Value | Description |
 |:------|:-------------------|
@@ -320,7 +320,7 @@ end
 """
  ismount(path) -> Bool
 
-Returns `true` if `path` is a mount point, `false` otherwise.
+Return `true` if `path` is a mount point, `false` otherwise.
 """
 function ismount(path...)
  path = joinpath(path...)