Better documentation and docs search for punctuation (JuliaLang#33344)

* Better documentation and docs search for punctuation * Update doc/src/base/punctuation.md Co-Authored-By: James Bradbury <[email protected]> * Update doc/src/base/punctuation.md Co-Authored-By: James Bradbury <[email protected]> * Fixup crosslinks working around JuliaDocs/Documenter.jl#781
halleysfifthinc · Oct 8, 2019 · 353b6c0 · 353b6c0
2 parents 14aaf76 + 8784619
commit 353b6c0
Show file tree

Hide file tree

Showing 8 changed files with 203 additions and 82 deletions.
diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl
@@ -348,6 +348,57 @@ For other purposes, `:( ... )` and `quote .. end` blocks are treated identically
 """
 kw"quote"
 
+"""
+ {}
+
+Curly braces are used to specify [type parameters](@ref man-parametric-types).
+
+Type parameters allow a single type declaration to introduce a whole family of
+new types — one for each possible combination of parameter values. For example,
+the [`Set`](@ref) type describes many possible types of sets; it uses one type
+parameter to describe the type of the elements it contains. The specific _parameterized_
+types `Set{Float64}` and `Set{Int64}` describe two _concrete_ types: both are
+subtypes ([`<:`](@ref)) of `Set`, but the former has `Float64` elements and the latter
+has `Int64` elements.
+"""
+kw"{", kw"{}", kw"}"
+
+"""
+ []
+
+Square braces are used for [indexing](@ref man-array-indexing), [indexed assignment](@ref man-indexed-assignment),
+[array literals](@ref man-array-literals), and [array comprehensions](@ref man-comprehensions).
+"""
+kw"[", kw"[]", kw"]"
+
+"""
+ ()
+
+Parentheses are used to group expressions, call functions, and construct [tuples](@ref Tuple) and [named tuples](@ref NamedTuple).
+"""
+kw"(", kw"()", kw")"
+
+"""
+ #
+
+The number sign (or hash) character is used to begin a single-line comment.
+"""
+kw"#"
+
+"""
+ #= =#
+
+A multi-line comment begins with `#=` and ends with `=#`, and may be nested.
+"""
+kw"#=", kw"=#"
+
+"""
+ ;
+
+Semicolons are used as statement separators and mark the beginning of keyword arguments in function declarations or calls.
+"""
+kw";"
+
 """
  Expr(head::Symbol, args...)
 

diff --git a/doc/src/base/punctuation.md b/doc/src/base/punctuation.md
@@ -4,44 +4,53 @@ Extended documentation for mathematical symbols & functions is [here](@ref math-
 
 | symbol | meaning |
 |:----------- |:----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@m` | invoke macro `m`; followed by space-separated expressions |
-| `!` | prefix "not" (logical negation) operator |
-| `a!( )` | at the end of a function name, `!` is used as a convention to indicate that a function modifies its argument(s) |
-| `#` | begin single line comment |
-| `#=` | begin multi-line comment (these are nestable) |
-| `=#` | end multi-line comment |
-| `$` | string and expression interpolation |
-| `%` | remainder operator |
-| `^` | exponent operator |
-| `&` | bitwise and |
-| `&&` | short-circuiting boolean and |
-| `\|` | bitwise or |
-| `\|\|` | short-circuiting boolean or |
-| `⊻` | bitwise xor operator |
-| `*` | multiply, or matrix multiply |
-| `()` | the empty tuple |
-| `~` | bitwise not operator |
-| `\` | backslash operator |
-| `'` | complex transpose operator Aᴴ |
-| `a[]` | array indexing (calling [`getindex`](@ref) or [`setindex!`](@ref)) |
-| `[,]` | vector literal constructor (calling [`vect`](@ref Base.vect)) |
-| `[;]` | vertical concatenation (calling [`vcat`](@ref) or [`hvcat`](@ref)) |
-| `[   ]` | with space-separated expressions, horizontal concatenation (calling [`hcat`](@ref) or [`hvcat`](@ref)) |
-| `T{ }` | parametric type instantiation |
-| `;` | statement separator |
-| `,` | separate function arguments or tuple components |
-| `?` | 3-argument conditional operator (used like: `conditional ? if_true : if_false`) |
-| `""` | delimit string literals |
-| `''` | delimit character literals |
-| ``` ` ` ``` | delimit external process (command) specifications |
-| `...` | splice arguments into a function call or declare a varargs function |
-| `.` | access named fields in objects/modules (calling [`getproperty`](@ref Base.getproperty) or [`setproperty!`](@ref Base.setproperty!)), also prefixes elementwise function calls (calling [`broadcast`](@ref)) |
-| `a:b` | range a, a+1, a+2, ..., b |
-| `a:s:b` | range a, a+s, a+2s, ..., b |
-| `:` | index an entire dimension (firstindex:lastindex), see [`Colon`](@ref)) |
-| `::` | type annotation or [`typeassert`](@ref), depending on context |
+| `@m` | the at-symbol invokes [macro](@ref man-macros) `m`; followed by space-separated expressions or a function-call-like argument list |
+| [`!`](@ref) | an exclamation mark is a prefix operator for logical negation ("not") |
+| `a!` | function names that end with an exclamation mark modify one or more of their arguments by convention |
+| `#` | the number sign (or hash or pound) character begins single line comments |
+| `#=` | when followed by an equals sign, it begins a multi-line comment (these are nestable) |
+| `=#` | end a multi-line comment by immediately preceding the number sign with an equals sign |
+| `$` | the dollar sign is used for [string](@ref string-interpolation) and [expression](@ref man-expression-interpolation) interpolation |
+| [`%`](@ref rem) | the percent symbol is the remainder operator |
+| [`^`](@ref) | the caret is the exponentiation operator. |
+| [`&`](@ref) | single ampersand is bitwise and |
+| [`&&`](@ref)| double ampersands is short-circuiting boolean and |
+| [`\|`](@ref)| single pipe character is bitwise or |
+| [`\|\|`](@ref) | double pipe characters is short-circuiting boolean or |
+| [`⊻`](@ref xor) | the unicode xor character is bitwise exclusive or |
+| [`~`](@ref) | the tilde is an operator for bitwise not |
+| `'` | a trailing apostrophe is the [`adjoint`](@ref) (that is, the complex transpose) operator Aᴴ |
+| [`*`](@ref) | the asterisk is used for multiplication, including matrix multiplication and [string concatenation](@ref man-concatenation) |
+| [`/`](@ref) | forward slash divides the argument on its left by the one on its right |
+| [`\`](@ref) | backslash operator divides the argument on its right by the one on its left, commonly used to solve matrix equations |
+| `()` | parentheses with no arguments constructs an empty [`Tuple`](@ref) |
+| `(a,...)` | parentheses with comma-separated arguments constructs a tuple containing its arguments |
+| `(a=1,...)` | parentheses with comma-separated assignments constructs a [`NamedTuple`](@ref) |
+| `(;)` | parentheses can also be used to group one or more semicolon separated expressions |
+| `a[]` | [array indexing](@ref man-array-indexing) (calling [`getindex`](@ref) or [`setindex!`](@ref)) |
+| `[,]` | [vector literal constructor](@ref man-array-literals) (calling [`vect`](@ref Base.vect)) |
+| `[;]` | [vertical concatenation](@ref man-array-concatenation) (calling [`vcat`](@ref) or [`hvcat`](@ref)) |
+| `[   ]` | with space-separated expressions, [horizontal concatenation](@ref man-concatenation) (calling [`hcat`](@ref) or [`hvcat`](@ref)) |
+| `T{ }` | curly braces following a type list that type's [parameters](@ref Parametric-Types) |
+| `{}` | curly braces can also be used to group multiple [`where`](@ref) expressions in function declarations |
+| `;` | semicolons separate statements, begin a list of keyword arguments in function declarations or calls, or are used to separate array literals for vertical concatenation |
+| `,` | commas separate function arguments or tuple or array components |
+| `?` | the question mark delimits the ternary conditional operator (used like: `conditional ? if_true : if_false`) |
+| `" "` | the single double-quote character delimits [`String`](@ref) literals |
+| `""" """` | three double-quote characters delimits string literals that may contain `"` and ignore leading indentation |
+| `' '` | the single-quote character delimits [`Char`](@ref) (that is, character) literals |
+| ``` ` ` ``` | the backtick character delimits [external process](@ref Running-External-Programs) ([`Cmd`](@ref)) literals |
+| `A...` | triple periods are a postfix operator that "splat" their arguments' contents into many arguments of a function call or declare a varargs function that "slurps" up many arguments into a single tuple |
+| `a.b` | single periods access named fields in objects/modules (calling [`getproperty`](@ref Base.getproperty) or [`setproperty!`](@ref Base.setproperty!)) |
+| `f.()` | periods may also prefix parentheses (like `f.(...)`) or infix operators (like `.+`) to perform the function element-wise (calling [`broadcast`](@ref)) |
+| `a:b` | colons ([`:`](@ref)) used as a binary infix operator construct a range from `a` to `b` (inclusive) with fixed step size `1` |
+| `a:s:b` | colons ([`:`](@ref)) used as a ternary infix operator construct a range from `a` to `b` (inclusive) with step size `s` |
+| `:` | when used by themselves, [`Colon`](@ref)s represent all indices within a dimension, frequently combined with [indexing](@ref man-array-indexing) |
+| `::` | double-colons represent a type annotation or [`typeassert`](@ref), depending on context, frequently used when declaring function arguments |
 | `:( )` | quoted expression |
-| `:a` | symbol a |
-| `<:` | [`subtype operator`](@ref <:) |
-| `>:` | [`supertype operator`](@ref >:) (reverse of subtype operator) |
-| `===` | [`egal comparison operator`](@ref ===) |
+| `:a` | [`Symbol`](@ref) a |
+| [`<:`](@ref)| subtype operator |
+| [`>:`](@ref)| supertype operator (reverse of subtype operator) |
+| `=` | single equals sign is [assignment](@ref man-variables) |
+| [`==`](@ref)| double equals sign is value equality comparison |
+| [`===`](@ref) | triple equals sign is programmatically identical equality comparison. |
diff --git a/doc/src/manual/arrays.md b/doc/src/manual/arrays.md
@@ -73,11 +73,7 @@ omitted it will default to [`Float64`](@ref).
 
 [^1]: *iid*, independently and identically distributed.
 
-The syntax `[A, B, C, ...]` constructs a 1-d array (i.e., a vector) of its arguments. If all
-arguments have a common [promotion type](@ref conversion-and-promotion) then they get
-converted to that type using [`convert`](@ref).
-
-To see the various ways we can pass dimensions to these constructors, consider the following examples:
+To see the various ways we can pass dimensions to these functions, consider the following examples:
 ```jldoctest
 julia> zeros(Int8, 2, 3)
 2×3 Array{Int8,2}:
@@ -94,60 +90,125 @@ julia> zeros((2, 3))
  0.0 0.0 0.0
  0.0 0.0 0.0
 ```
-Here, `(2, 3)` is a [`Tuple`](@ref).
-
-## Concatenation
+Here, `(2, 3)` is a [`Tuple`](@ref) and the first argument — the element type — is optional, defaulting to `Float64`.
 
-Arrays can be constructed and also concatenated using the following functions:
+## [Array literals](@id man-array-literals)
 
-| Function | Description |
-|:--------------------------- |:----------------------------------------------- |
-| [`cat(A...; dims=k)`](@ref) | concatenate input arrays along dimension(s) `k` |
-| [`vcat(A...)`](@ref) | shorthand for `cat(A...; dims=1)` |
-| [`hcat(A...)`](@ref) | shorthand for `cat(A...; dims=2)` |
+Arrays can also be directly constructed with square braces; the syntax `[A, B, C, ...]`
+creates a one dimensional array (i.e., a vector) containing the comma-separated arguments as
+its elements. The element type ([`eltype`](@ref)) of the resulting array is automatically
+determined by the types of the arguments inside the braces. If all the arguments are the
+same type, then that is its `eltype`. If they all have a common
+[promotion type](@ref conversion-and-promotion) then they get converted to that type using
+[`convert`](@ref) and that type is the array's `eltype`. Otherwise, a heterogeneous array
+that can hold anything — a `Vector{Any}` — is constructed; this includes the literal `[]`
+where no arguments are given.
 
-Scalar values passed to these functions are treated as 1-element arrays. For example,
 ```jldoctest
-julia> vcat([1, 2], 3)
+julia> [1,2,3] # An array of `Int`s
 3-element Array{Int64,1}:
  1
  2
  3
 
-julia> hcat([1 2], 3)
-1×3 Array{Int64,2}:
- 1 2 3
+julia> promote(1, 2.3, 4//5) # This combination of Int, Float64 and Rational promotes to Float64
+(1.0, 2.3, 0.8)
+
+julia> [1, 2.3, 4//5] # Thus that's the element type of this Array
+3-element Array{Float64,1}:
+ 1.0
+ 2.3
+ 0.8
+
+julia> []
+0-element Array{Any,1}
 ```
 
-The concatenation functions are used so often that they have special syntax:
+### [Concatenation](@id man-array-concatenation)
 
-| Expression | Calls |
-|:----------------- |:----------------- |
-| `[A; B; C; ...]` | [`vcat`](@ref) |
-| `[A B C ...]` | [`hcat`](@ref) |
-| `[A B; C D; ...]` | [`hvcat`](@ref) |
+If the arguments inside the square brackets are separated by semicolons (`;`) or newlines
+instead of commas, then their contents are _vertically concatenated_ together instead of
+the arguments being used as elements themselves.
 
-[`hvcat`](@ref) concatenates in both dimension 1 (with semicolons) and dimension 2 (with spaces).
-Consider these examples of this syntax:
 ```jldoctest
-julia> [[1; 2]; [3, 4]]
+julia> [1:2, 4:5] # Has a comma, so no concatenation occurs. The ranges are themselves the elements
+2-element Array{UnitRange{Int64},1}:
+ 1:2
+ 4:5
+
+julia> [1:2; 4:5]
 4-element Array{Int64,1}:
  1
  2
- 3
  4
+ 5
 
-julia> [[1 2] [3 4]]
-1×4 Array{Int64,2}:
- 1 2 3 4
+julia> [1:2; 4:5]
+4-element Array{Int64,1}:
+ 1
+ 2
+ 4
+ 5
+
+julia> [1:2
+ 4:5
+ 6]
+5-element Array{Int64,1}:
+ 1
+ 2
+ 4
+ 5
+ 6
+```
+
+Similarly, if the arguments are separated by tabs or spaces, then their contents are
+_horizontally concatenated_ together.
+
+```jldoctest
+julia> [1:2 4:5 7:8]
+2×3 Array{Int64,2}:
+ 1 4 7
+ 2 5 8
+
+julia> [[1,2] [4,5] [7,8]]
+2×3 Array{Int64,2}:
+ 1 4 7
+ 2 5 8
+
+julia> [1 2 3] # Numbers can also be horizontally concatenated
+1×3 Array{Int64,2}:
+ 1 2 3
+```
+
+Using semicolons (or newlines) and spaces (or tabs) can be combined to concatenate
+both horizontally and vertically at the same time.
 
-julia> [[1 2]; [3 4]]
+```jldoctest
+julia> [1 2
+ 3 4]
 2×2 Array{Int64,2}:
  1 2
  3 4
+
+julia> [zeros(Int, 2, 2) [1; 2]
+ [3 4] 5]
+3×3 Array{Int64,2}:
+ 0 0 1
+ 0 0 2
+ 3 4 5
 ```
 
-## Typed array initializers
+More generally, concatenation can be accomplished through the [`cat`](@ref) function.
+These syntaxes are shorthands for function calls that themselves are convenience functions:
+
+| Syntax | Function | Description |
+|:----------------- |:--------------- |:-------------------------------------------------- |
+| | [`cat`](@ref) | concatenate input arrays along dimension(s) `k` |
+| `[A; B; C; ...]` | [`vcat`](@ref) | shorthand for `cat(A...; dims=1) |
+| `[A B C ...]` | [`hcat`](@ref) | shorthand for `cat(A...; dims=2) |
+| `[A B; C D; ...]` | [`hvcat`](@ref) | simultaneous vertical and horizontal concatenation |
+
+### Typed array literals
 
 An array with a specific element type can be constructed using the syntax `T[A, B, C, ...]`. This
 will construct a 1-d array with element type `T`, initialized to contain elements `A`, `B`, `C`,
@@ -166,7 +227,7 @@ julia> Int8[[1 2] [3 4]]
  1 2 3 4
 ```
 
-## Comprehensions
+## [Comprehensions](@id man-comprehensions)
 
 Comprehensions provide a general and powerful way to construct arrays. Comprehension syntax is
 similar to set construction notation in mathematics:
@@ -206,7 +267,7 @@ julia> [ 0.25*x[i-1] + 0.5*x[i] + 0.25*x[i+1] for i=2:length(x)-1 ]
  0.656511
 ```
 
-The resulting array type depends on the types of the computed elements. In order to control the
+The resulting array type depends on the types of the computed elements just like [array literals](@ref man-array-literals) do. In order to control the
 type explicitly, a type can be prepended to the comprehension. For example, we could have requested
 the result in single precision by writing:
 
@@ -397,7 +458,7 @@ julia> x[1, [2 3; 4 1]]
  13 1
 ```
 
-## Assignment
+## [Indexed Assignment](@id man-indexed-assignment)
 
 The general syntax for assigning values in an n-dimensional array `A` is:
 

diff --git a/doc/src/manual/integers-and-floating-point-numbers.md b/doc/src/manual/integers-and-floating-point-numbers.md
@@ -216,7 +216,7 @@ UInt128: [0,340282366920938463463374607431768211455]
 
 The values returned by [`typemin`](@ref) and [`typemax`](@ref) are always of the given argument
 type. (The above expression uses several features that have yet to be introduced, including [for loops](@ref man-loops),
-[Strings](@ref man-strings), and [Interpolation](@ref), but should be easy enough to understand for users
+[Strings](@ref man-strings), and [Interpolation](@ref string-interpolation), but should be easy enough to understand for users
 with some existing programming experience.)
 
 ### Overflow behavior

diff --git a/doc/src/manual/metaprogramming.md b/doc/src/manual/metaprogramming.md
@@ -199,7 +199,7 @@ julia> typeof(ex)
 Expr
 ```
 
-### Interpolation
+### [Interpolation](@id man-expression-interpolation)
 
 Direct construction of [`Expr`](@ref) objects with value arguments is powerful, but `Expr` constructors
 can be tedious compared to "normal" Julia syntax. As an alternative, Julia allows *interpolation* of