doc: drop colon from "See also" sentences (#40401)

We generally seem to prefer sentences over keyword lists (which feel a bit too much like Javadoc to me), so this changes the documentation to use a more free-form sentence for "see also," including an ending period (we seem to have intuitively preferred this already, by a ratio of 5:2).
JuliaLang · May 28, 2021 · 93d375c · 93d375c
1 parent 5dbf45a
commit 93d375c
Show file tree

Hide file tree

Showing 33 changed files with 99 additions and 99 deletions.
diff --git a/base/abstractarray.jl b/base/abstractarray.jl
@@ -2740,7 +2740,7 @@ mapany(f, itr) = Any[f(x) for x in itr]
 Transform collection `c` by applying `f` to each element. For multiple collection arguments,
 apply `f` elementwise, and stop when when any of them is exhausted.
 
-See also: [`map!`](@ref), [`foreach`](@ref), [`mapreduce`](@ref), [`mapslices`](@ref), [`zip`](@ref), [`Iterators.map`](@ref).
+See also [`map!`](@ref), [`foreach`](@ref), [`mapreduce`](@ref), [`mapslices`](@ref), [`zip`](@ref), [`Iterators.map`](@ref).
 
 # Examples
 ```jldoctest

diff --git a/base/array.jl b/base/array.jl
@@ -499,7 +499,7 @@ function zeros end
     ones([T=Float64,] dims...)
 
 Create an `Array`, with element type `T`, of all ones with size specified by `dims`.
-See also: [`fill`](@ref), [`zeros`](@ref).
+See also [`fill`](@ref), [`zeros`](@ref).
 
 # Examples
 ```jldoctest

diff --git a/base/char.jl b/base/char.jl
@@ -108,17 +108,19 @@ end
     ismalformed(c::AbstractChar) -> Bool
 
 Return `true` if `c` represents malformed (non-Unicode) data according to the
-encoding used by `c`.  Defaults to `false` for non-`Char` types.  See also
-[`show_invalid`](@ref).
+encoding used by `c`. Defaults to `false` for non-`Char` types.
+
+See also [`show_invalid`](@ref).
 """
 ismalformed(c::AbstractChar) = false
 
 """
     isoverlong(c::AbstractChar) -> Bool
 
 Return `true` if `c` represents an overlong UTF-8 sequence. Defaults
-to `false` for non-`Char` types.  See also [`decode_overlong`](@ref)
-and [`show_invalid`](@ref).
+to `false` for non-`Char` types.
+
+See also [`decode_overlong`](@ref) and [`show_invalid`](@ref).
 """
 isoverlong(c::AbstractChar) = false
 

diff --git a/base/div.jl b/base/div.jl
@@ -12,7 +12,7 @@ an integer according to the rounding mode `r`. In other words, the quantity
 
 without any intermediate rounding.
 
-See also: [`fld`](@ref), [`cld`](@ref) which are special cases of this function
+See also [`fld`](@ref) and [`cld`](@ref), which are special cases of this function.
 
 # Examples:
 ```jldoctest
@@ -88,7 +88,7 @@ rem(x::Integer, y::Integer, r::RoundingMode{:Nearest}) = divrem(x, y, r)[2]
 
 Largest integer less than or equal to `x/y`. Equivalent to `div(x, y, RoundDown)`.
 
-See also: [`div`](@ref), [`cld`](@ref), [`fld1`](@ref).
+See also [`div`](@ref), [`cld`](@ref), [`fld1`](@ref).
 
 # Examples
 ```jldoctest
@@ -122,7 +122,7 @@ fld(a, b) = div(a, b, RoundDown)
 
 Smallest integer larger than or equal to `x/y`. Equivalent to `div(x, y, RoundUp)`.
 
-See also: [`div`](@ref), [`fld`](@ref).
+See also [`div`](@ref), [`fld`](@ref).
 
 # Examples
 ```jldoctest

diff --git a/base/initdefs.jl b/base/initdefs.jl
@@ -81,8 +81,7 @@ Here is an overview of some of the subdirectories that may exist in a depot:
 * `packages`: Contains packages, some of which were explicitly installed and some which are implicit dependencies. Maintained by `Pkg.jl`.
 * `registries`: Contains package registries. By default only `General`. Maintained by `Pkg.jl`.
 
-See also:
-[`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH), and
+See also [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH), and
 [Code Loading](@ref code-loading).
 """
 const DEPOT_PATH = String[]
@@ -161,7 +160,7 @@ have special meanings:
 The fully expanded value of `LOAD_PATH` that is searched for projects and packages
 can be seen by calling the `Base.load_path()` function.
 
-See also:
+See also
 [`JULIA_LOAD_PATH`](@ref JULIA_LOAD_PATH),
 [`JULIA_PROJECT`](@ref JULIA_PROJECT),
 [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH), and

diff --git a/base/intfuncs.jl b/base/intfuncs.jl
@@ -953,6 +953,8 @@ Factorial of `n`. If `n` is an [`Integer`](@ref), the factorial is computed as a
 integer (promoted to at least 64 bits). Note that this may overflow if `n` is not small,
 but you can use `factorial(big(n))` to compute the result exactly in arbitrary precision.
 
+See also [`binomial`](@ref).
+
 # Examples
 ```jldoctest
 julia> factorial(6)
@@ -967,9 +969,6 @@ julia> factorial(big(21))
 51090942171709440000
 ```
 
-# See also
-* [`binomial`](@ref)
-
 # External links
 * [Factorial](https://en.wikipedia.org/wiki/Factorial) on Wikipedia.
 """
@@ -999,6 +998,8 @@ If ``n`` is negative, then it is defined in terms of the identity
 \\binom{n}{k} = (-1)^k \\binom{k-n-1}{k}
 ```
 
+See also [`factorial`](@ref).
+
 # Examples
 ```jldoctest
 julia> binomial(5, 3)
@@ -1011,9 +1012,6 @@ julia> binomial(-5, 3)
 -35
 ```
 
-# See also
-* [`factorial`](@ref)
-
 # External links
 * [Binomial coefficient](https://en.wikipedia.org/wiki/Binomial_coefficient) on Wikipedia.
 """

diff --git a/base/io.jl b/base/io.jl
@@ -1034,7 +1034,7 @@ end
 
 Return an iterable object yielding [`read(io, T)`](@ref).
 
-See also: [`skipchars`](@ref), [`eachline`](@ref), [`readuntil`](@ref)
+See also [`skipchars`](@ref), [`eachline`](@ref), [`readuntil`](@ref).
 
 !!! compat "Julia 1.6"
     `readeach` requires Julia 1.6 or later.

diff --git a/base/iterators.jl b/base/iterators.jl
@@ -221,7 +221,7 @@ CartesianIndex(1, 2) d
 CartesianIndex(2, 2) e
 ```
 
-See also: [`IndexStyle`](@ref), [`axes`](@ref).
+See also [`IndexStyle`](@ref), [`axes`](@ref).
 """
 pairs(::IndexLinear,    A::AbstractArray) = Pairs(A, LinearIndices(A))
 pairs(::IndexCartesian, A::AbstractArray) = Pairs(A, CartesianIndices(axes(A)))
@@ -1338,7 +1338,7 @@ length(s::Stateful) = length(s.itr) - s.taken
 Returns the one and only element of collection `x`, and throws an `ArgumentError` if the
 collection has zero or multiple elements.
 
-See also: [`first`](@ref), [`last`](@ref).
+See also [`first`](@ref), [`last`](@ref).
 
 !!! compat "Julia 1.4"
     This method requires at least Julia 1.4.

diff --git a/base/libc.jl b/base/libc.jl
@@ -131,7 +131,7 @@ Suspends execution for `s` seconds.
 This function does not yield to Julia's scheduler and therefore blocks
 the Julia thread that it is running on for the duration of the sleep time.
 
-See also: [`sleep`](@ref)
+See also [`sleep`](@ref).
 """
 systemsleep
 

diff --git a/base/mpfr.jl b/base/mpfr.jl
@@ -151,6 +151,11 @@ global precision; `convert` will always return `x`.
 convenience since decimal literals are converted to `Float64` when parsed, so
 `BigFloat(2.1)` may not yield what you expect.
 
+See also:
+- [`@big_str`](@ref)
+- [`rounding`](@ref) and [`setrounding`](@ref)
+- [`precision`](@ref) and [`setprecision`](@ref)
+
 !!! compat "Julia 1.1"
     `precision` as a keyword argument requires at least Julia 1.1.
     In Julia 1.0 `precision` is the second positional argument (`BigFloat(x, precision)`).
@@ -169,11 +174,6 @@ julia> BigFloat("2.1", RoundUp)
 julia> BigFloat("2.1", RoundUp, precision=128)
 2.100000000000000000000000000000000000007
 ```
-
-# See also
-- [`@big_str`](@ref)
-- [`rounding`](@ref) and [`setrounding`](@ref)
-- [`precision`](@ref) and [`setprecision`](@ref)
 """
 BigFloat(x, r::RoundingMode)
 

diff --git a/base/operators.jl b/base/operators.jl
@@ -508,7 +508,9 @@ min(x,y) = ifelse(isless(y, x), y, x)
 """
     minmax(x, y)
 
-Return `(min(x,y), max(x,y))`. See also: [`extrema`](@ref) that returns `(minimum(x), maximum(x))`.
+Return `(min(x,y), max(x,y))`.
+
+See also [`extrema`](@ref) that returns `(minimum(x), maximum(x))`.
 
 # Examples
 ```jldoctest
@@ -873,7 +875,7 @@ const ÷ = div
 Modulus after flooring division, returning a value `r` such that `mod(r, y) == mod(x, y)`
 in the range ``(0, y]`` for positive `y` and in the range ``[y,0)`` for negative `y`.
 
-See also: [`fld1`](@ref), [`fldmod1`](@ref).
+See also [`fld1`](@ref), [`fldmod1`](@ref).
 
 # Examples
 ```jldoctest
@@ -892,7 +894,7 @@ mod1(x::T, y::T) where {T<:Real} = (m = mod(x, y); ifelse(m == 0, y, m))
 
 Flooring division, returning a value consistent with `mod1(x,y)`
 
-See also: [`mod1`](@ref), [`fldmod1`](@ref).
+See also [`mod1`](@ref), [`fldmod1`](@ref).
 
 # Examples
 ```jldoctest
@@ -919,7 +921,7 @@ end
 
 Return `(fld1(x,y), mod1(x,y))`.
 
-See also: [`fld1`](@ref), [`mod1`](@ref).
+See also [`fld1`](@ref), [`mod1`](@ref).
 """
 fldmod1(x, y) = (fld1(x, y), mod1(x, y))
 

diff --git a/base/pair.jl b/base/pair.jl
@@ -23,7 +23,7 @@ Construct a `Pair` object with type `Pair{typeof(x), typeof(y)}`. The elements
 are stored in the fields `first` and `second`. They can also be accessed via
 iteration (but a `Pair` is treated as a single "scalar" for broadcasting operations).
 
-See also: [`Dict`](@ref)
+See also [`Dict`](@ref).
 
 # Examples
 ```jldoctest

diff --git a/base/path.jl b/base/path.jl
@@ -159,7 +159,7 @@ julia> dirname("/home/myuser/")
 "/home/myuser"
 ```
 
-See also: [`basename`](@ref)
+See also [`basename`](@ref).
 """
  dirname(path::AbstractString) = splitdir(path)[1]
 
@@ -181,7 +181,7 @@ julia> basename("/home/myuser/")
 ""
 ```
 
-See also: [`dirname`](@ref)
+See also [`dirname`](@ref).
 """
 basename(path::AbstractString) = splitdir(path)[2]
 

diff --git a/base/permuteddimsarray.jl b/base/permuteddimsarray.jl
@@ -24,7 +24,7 @@ Given an AbstractArray `A`, create a view `B` such that the
 dimensions appear to be permuted. Similar to `permutedims`, except
 that no copying occurs (`B` shares storage with `A`).
 
-See also: [`permutedims`](@ref), [`invperm`](@ref).
+See also [`permutedims`](@ref), [`invperm`](@ref).
 
 # Examples
 ```jldoctest
@@ -86,7 +86,7 @@ end
 Permute the dimensions of array `A`. `perm` is a vector or a tuple of length `ndims(A)`
 specifying the permutation.
 
-See also: [`permutedims!`](@ref), [`PermutedDimsArray`](@ref), [`transpose`](@ref), [`invperm`](@ref).
+See also [`permutedims!`](@ref), [`PermutedDimsArray`](@ref), [`transpose`](@ref), [`invperm`](@ref).
 
 # Examples
 ```jldoctest

diff --git a/base/pointer.jl b/base/pointer.jl
@@ -125,7 +125,7 @@ Convert a `Ptr` to an object reference. Assumes the pointer refers to a valid he
 Julia object. If this is not the case, undefined behavior results, hence this function is
 considered "unsafe" and should be used with care.
 
-See also: [`pointer_from_objref`](@ref).
+See also [`pointer_from_objref`](@ref).
 """
 unsafe_pointer_to_objref(x::Ptr) = ccall(:jl_value_ptr, Any, (Ptr{Cvoid},), x)
 
@@ -139,7 +139,7 @@ remains referenced for the whole time that the `Ptr` will be used.
 This function may not be called on immutable objects, since they do not have
 stable memory addresses.
 
-See also: [`unsafe_pointer_to_objref`](@ref).
+See also [`unsafe_pointer_to_objref`](@ref).
 """
 function pointer_from_objref(@nospecialize(x))
     @_inline_meta

diff --git a/base/range.jl b/base/range.jl
@@ -1282,7 +1282,7 @@ end
 Find `y` in the range `r` such that ``x ≡ y (mod n)``, where `n = length(r)`,
 i.e. `y = mod(x - first(r), n) + first(r)`.
 
-See also: [`mod1`](@ref).
+See also [`mod1`](@ref).
 
 # Examples
 ```jldoctest

diff --git a/base/shell.jl b/base/shell.jl
@@ -322,7 +322,7 @@ run(setenv(`cmd /C echo %cmdargs%`, "cmdargs" => cmdargs))
 With an I/O stream parameter `io`, the result will be written there,
 rather than returned as a string.
 
-See also: [`escape_microsoft_c_args`](@ref), [`shell_escape_posixly`](@ref)
+See also [`escape_microsoft_c_args`](@ref), [`shell_escape_posixly`](@ref).
 
 # Example
 ```jldoctest
@@ -376,7 +376,7 @@ It joins command-line arguments to be passed to a Windows
 C/C++/Julia application into a command line, escaping or quoting the
 meta characters space, TAB, double quote and backslash where needed.
 
-See also: [`shell_escape_wincmd`](@ref), [`escape_raw_string`](@ref)
+See also [`shell_escape_wincmd`](@ref), [`escape_raw_string`](@ref).
 """
 function escape_microsoft_c_args(io::IO, args::AbstractString...)
     # http://daviddeley.com/autohotkey/parameters/parameters.htm#WINCRULES

diff --git a/base/sort.jl b/base/sort.jl
@@ -383,13 +383,14 @@ julia> searchsortedlast([1, 2, 4, 5, 5, 7], 0) # no match, insert at start
 """ searchsortedlast
 
 """
-    insorted(a, x; by=<transform>, lt=<comparison>, rev=false)
+    insorted(a, x; by=<transform>, lt=<comparison>, rev=false) -> Bool
 
 Determine whether an item is in the given sorted collection, in the sense that
 it is [`==`](@ref) to one of the values of the collection according to the order
 specified by the `by`, `lt` and `rev` keywords, assuming that `a` is already
-sorted in that order, see [`sort`](@ref) for the keywords. See also
-[`in`](@ref). Returns a `Bool` value.
+sorted in that order, see [`sort`](@ref) for the keywords.
+
+See also [`in`](@ref).
 
 # Examples
 ```jldoctest

diff --git a/base/stat.jl b/base/stat.jl
@@ -187,7 +187,7 @@ julia> isdir("not/a/directory")
 false
 ```
 
-See also: [`isfile`](@ref) and [`ispath`](@ref).
+See also [`isfile`](@ref) and [`ispath`](@ref).
 """
 isdir(st::StatStruct) = filemode(st) & 0xf000 == 0x4000
 
@@ -216,7 +216,7 @@ true
 julia> close(f); rm("test_file.txt")
 ```
 
-See also: [`isdir`](@ref) and [`ispath`](@ref).
+See also [`isdir`](@ref) and [`ispath`](@ref).
 """
 isfile(st::StatStruct) = filemode(st) & 0xf000 == 0x8000