[v3] Update Markdown files to latest spec

concepts/arrays/about.md

@@ -1,3 +1,5 @@
+# About
+
 [Arrays][array] are one of Swift's three primary collection types. Arrays are ordered lists of elements where the elements can be of any type, however, all elements of any given list must have the same type.
 
 Arrays literals are written as a series of elements, each separated by commas, enclosed in square brackets. Empty arrays are just a pair of square brackets. Type names for arrays are written in one of two ways: `Array<T>` or `[T]` where `T` is the type of the elements in thee array. When creating an empty array, the type must be specified.

concepts/arrays/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Arrays are one of Swift's three primary collection types. Arrays are ordered lists of elements where the elements can be of any type, however, all elements of any given list must have the same type.
 
 Arrays literals are written as a series of elements, each separated by commas, enclosed in square brackets. Empty arrays are just a pair of square brackets. Type names for arrays are written in one of two ways: `Array<T>` or `[T]` where `T` is the type of the elements in the array. When creating an empty array, the type must be specified.

concepts/basics/about.md

@@ -1,3 +1,5 @@
+# About
+
 Swift has values of a number of fundamental data types that are similar to what is seen in other programming languages, including integers, booleans, and floating point numbers. In addition to these types, Swift also offers a number of more complex types that values can be, including arrays, dictionaries, and functions.
 
 Swift supports two types of [comments][comments]. Single line comments are preceded by `//` and multiline comments are inserted between `/*` and `*/`.

concepts/basics/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## basics

concepts/booleans/about.md

@@ -1,3 +1,5 @@
+# About
+
 One of Swift's basic types is the [Boolean type][booleans], called `Bool`. Swift provides two Boolean constant values, `true` and `false`:
 
 ```swift

concepts/booleans/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## booleans

concepts/capturing/about.md

@@ -1,3 +1,5 @@
+# About
+
 In Swift, closures and functions (which are just special cases of closures) are able to access the parameters and variables of their surrounding environment. Additionally, they are able to maintain access to these values after the enclosing function terminates. This action of obtaining and maintaining access is known as [_capturing_][capturing-values].
 
 ```swift

concepts/characters/introduction.md

@@ -1 +1,3 @@
+# Introduction
+
 TODO: add introduction for characters concept

concepts/classes/introduction.md

@@ -1 +1,3 @@
+# Introduction
+
 TODO: add introduction for classes concept

concepts/closures/about.md

@@ -1,3 +1,5 @@
+# About
+
 [Closures][closures] in Swift are self-contained blocks of code that can be passed parameters to trigger their computation and return values. Closures also capture values from their environment and use them in their computations. As they are self contained, they may be passed around in a program like other values or assigned to constants and variables.
 
 Closures may sound a lot like Swift functions; they do, and for good reason. Functions in swift are just special cases of closures which are required to have a name and are defined using a slightly different syntax.
@@ -46,7 +48,7 @@ func makeAdder(base: Int) -> (Int) -> Int {
 }
 ```
 
-### Inferring closure types
+## Inferring closure types
 
 When the return type or parameter types can be [inferred from context][inferring-closure-types], they can be omitted from the closure expression. Additionally, if the parameter types can be omitted, so can the parentheses around the parameter names:
 
@@ -64,7 +66,7 @@ func makeAdder(base: Int) -> (Int) -> Int {
 - In the second, the compiler knows from the definition of `makeAdder` that `base` is an int and that the returned function must be of type `(Int) -> Int`. From there, it can verify that if `x` is an `Int` then the closure will have type `(Int) -> Int`, and thus we can omit they type signature in the closure as `(Int) -> Int` is the only possible valid signature the closure may have.
 - The third example is similar, but the compiler needs get some of the type information from the array that the method is being used with. It knows that the `sorted(by:)` method takes as a parameter a closure with two parameters that are the same type as the elements of the collection being sorted, and which returns a `Bool`, so the compiler can infer that the return type of the closure must be `Bool`. And since the method is being used with a String array, it can determine that the types of the parameters `s1`, and `s2` must both be `String`.
 
-### Limitations of closures
+## Limitations of closures
 
 As mentioned above, functions and closures are very similar in Swift, but there are some important differences:
 

concepts/conditionals-guard/about.md

@@ -1,3 +1,5 @@
+# About
+
 The `guard` statement in Swift is used for early returns from Swift functions when a necessary condition which needs to be met for further processing to continue is not met, e.g.:
 
 ```swift

concepts/conditionals-guard/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## booleans

concepts/conditionals-if/about.md

@@ -1,3 +1,5 @@
+# About
+
 If statements in Swift are similar to those seen in other languages. E.g.:
 
 ```swift
@@ -12,7 +14,7 @@ With this structure, if the Boolean expression following the `if` evaluates as `
 
 There are two variants of this pattern that are available in Swift, the else-if and the no-else variants.
 
-### else-if
+## else-if
 
 In cases where the second block of code would just be another `if` statement, the else-if allows us to clean up the code and remove some indentation from our code by moving the `if` up next to the previous `else` and getting rid of a layer of parentheses.
 
@@ -30,7 +32,7 @@ if str == "apple" {
 }
 ```
 
-### no-else
+## no-else
 
 And if any if-statement only needs to perform code for one of the cases, the else branch can be left out entirely. So for example, if you are writing software that diagnoses patients and you need to log certain symptoms, like elevated heart rate, instead of writing:
 

concepts/conditionals-if/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## booleans

concepts/conditionals-switch/about.md

@@ -1,3 +1,5 @@
+# About
+
 ```swift
 if str == "apple" {
     print("Let's bake an apple crumble")
@@ -33,7 +35,7 @@ Additionally, note that if multiple cases of a switch statement match the input
 
 Unlike in some other languages, `switch` cases in Swift do not fall through to the next case unless that behavior is explicitly called for with the `fallthrough` keyword. this is the opposite behavior from C which requires explicit `break` statements to prevent fallthrough.
 
-### Binding and where statements
+## Binding and where statements
 
 The values being matched in `switch` statements can also be bound to names which can be used in the body of the case. They can also be used in `where` clauses, which are additional boolean expressions that must evaluate as `true` for the case to match.
 

concepts/conditionals-switch/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## booleans

concepts/conditionals/about.md

@@ -1 +1,3 @@
+# About
+
 TODO: add information on conditionals concept

concepts/conditionals/introduction.md

@@ -1 +1,3 @@
+# Introduction
+
 TODO: add introduction for conditionals concept

concepts/constants-and-variables/about.md

@@ -1,3 +1,5 @@
+# About
+
 Values in Swift can be associated with [names][naming] in one of two ways, by assigning them to a variable or by assigning them to a constant. That name may then be used to refer to that value throughout the program. Constants are immutable, which means that the value cannot be changed. Variables, on the other hand, are mutable, which means that the value can be changed at any time.
 
 Once you’ve declared a constant or variable of a certain type, you can’t declare it again with the same name, or change it to store values of a different type. Nor can you change a constant into a variable or a variable into a constant.

concepts/constants/about.md

@@ -0,0 +1,2 @@
+# About
+

concepts/constants/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## basics

concepts/control-transfer/about.md

@@ -1,6 +1,8 @@
+# About
+
 The normal control flow of loops in Swift can be altered using [Swift's control transfer keywords][control-transfer]. One of these keywords, `return` has been seen before in the basics concept exercise. With the use of `return`, if the loop is inside a function, the function will exit at that point, returning whatever value is specified, just as it would at any other point in a function. Two more control transfer keywords that are often used with loops are `continue` and `break`.
 
-### continue
+## continue
 
 When the `continue` keyword is executed inside a loop, it tells the loop to skip immediately to the next iteration of the loop, skipping any lines of code that may lie between it and the end of the body of the loop. Note that execution resumes with the next evaluation of the Boolean expression for while and repeat-while loops, and not directly to the start of the loop body. So this loop:
 
@@ -29,7 +31,7 @@ rather than:
 6
 ```
 
-### break
+## break
 
 When the `break` keyword is executed inside a loop, it tells the loop to jump immediately out of the loop and to resume execution with the first statement following the body of the loop, skipping any lines of code that may lie between it and the end of the body of the loop and not attempting to start another iteration of the loop.
 
@@ -44,7 +46,7 @@ for fruit in ["banana", "grapes", "apple", "strawberry", "kiwi", "lemon"] {
 // grapes
 ```
 
-### labels
+## labels
 
 When loops are nested, there are times when one may want to use `break` or `continue` to exit or restart the outer loops that contain the loop in which the `break` or `continue` are used. In cases like these, [labels may be used][labeled-statements] to specify the loop to be exited or restarted. A loop can be labeled by putting a name followed by a colon before the `while`, `repeat`, or `for` that starts the loop.
 

concepts/control-transfer/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## loops

concepts/default-parameters/about.md

@@ -1,4 +1,4 @@
-## Default parameter values
+# Default parameter values
 
 [Default parameter values][default-parameter-values] can be supplied for any of a function's parameters by assigning a value to the parameter in the parameter list following the parameter's type annotation. When a default parameter value is specified, the caller of the function can omit that parameter when calling the function and the default value will be used instead.
 

concepts/default-parameters/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## function-overloading

concepts/dictionaries/about.md

@@ -1,3 +1,5 @@
+# About
+
 As [dictionaries][dictionaries] are one of Swift's three primary collection types, knowing how to work with dictionaries is a big part of knowing how to program in Swift.
 
 ## Key Takeaways from this Exercise

concepts/dictionaries/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 Dictionaries are one of Swift's three primary collection types. Dictionaries store mappings between _keys_ which are elements of one type and _values_ which are elements of another type (possibly the same type as that of the keys).
 
 Dictionary literals are written as a series of `key: value` pairs, separated by commas, enclosed in square brackets. Empty dictionaries can be written by following the type name of the dictionary by a pair of parenthesis, e.g. `[Int: String]()`, or, if the type can be determined from the context, as just a pair of square brackets surrounding a colon, `[:]`. Type names for dictionaries are written in one of two ways: `Dictionary<K, V>` or `[K: V]` where `K` is the type of the keys in the dictionary and `V` is the type of the values. When creating an empty array, the type must be specified.

concepts/enumerations/about.md

@@ -1,3 +1,5 @@
+# About
+
 The built-in Swift types have a number of problems when used to model something with a moderate number of possible states or values, like the 63 official HTTP status codes, or the 8 buttons of the NES controller.
 
 For example, one may try to use existing types like strings or ints to represent their values, similar to what was done with the HTTP status codes, but this leads to a few different issues. One issue is that, while a computer may be fine processing valid values like 103, 226, and 505, the program itself also has to constantly check that it doesn't receive invalid values like 213, 427, 512, or 601. At the same time the _programmer_ is responsible for ensuring that every valid value is checked when examining a code to act upon, so a valid code isn't missed.
@@ -10,7 +12,7 @@ As an approach to solving this problem, Swift, like many modern languages offers
 
 Enums in Swift are a mechanism of creating new types which are inhabited by a finite number of named values which may carry additional associated information, and which can be checked at compile time for completeness and accuracy of use. Additionally, enums can have properties and methods attached to them, providing additional information and functionality based on the current value of the enum.
 
-### Defining Enums
+## Defining Enums
 
 The most basic enums are defined in Swift by the `enum` keyword followed by the name of the type and then the body of the enum enclosed in curly braces, which includes a list of the values of the enum, introduced with the `case` keyword. Following the [Swift style guide][api-design-guidelines], the name of the type should be in UpperCamelCase while the values should be in lowerCamelCase.
 
@@ -48,7 +50,7 @@ let konamiCode = [NESButton.up, .up, .down, .down, .left, .right, .left, .right,
 
 Notice that, since all of the elements of an array must be of the same type, we only need to supply the type name for one of the elements, the rest can be just the values. The type name wouldn't be required for any of them if the constant was given the proper type annotation, e.g. `let konamiCode: [NESButton] = …`.
 
-### Enums and switch statements
+## Enums and switch statements
 
 Enums are frequently used [alongside `switch` statements][enums-and-switches] which are used to determine the action to take based on the value of the enum.
 
@@ -113,15 +115,15 @@ lastPressed = .selcet
 // Error: Type 'NESButton' has no member 'selcet'
 ```
 
-### Methods
+## Methods
 
 Like other types in Swift, enums may contain methods which allow the enum to provide functionality based on the current value of the enum.
 
 Methods are analogous to functions, only they are defined inside the body of the enum and they are tied to the current enum value. They are accessed via _dot notation_ where the name of the enum value is followed by a dot (`.`) and the name of the method and its parameters.
 
 Inside the method, the enum value can be referred to as `self`, and in the type signature, if one is accepting as a parameter or returning a value of the the enum they can refer to the type as `Self`.
 
-#### Initializers
+### Initializers
 
 Initializers are special methods that are used to set up a value of the enum. Their definition looks a lot like that of a method only there is no `func` keyword, no return type, and the name must be `init` and the initializer _must_ assign a value of the enum to `self`. Initializers are called either via dot notation or by passing the initializer's parameters to the name of the enum.
 

concepts/enumerations/introduction.md

@@ -1,6 +1,8 @@
+# Introduction
+
 Enums in Swift are a mechanism of creating new types which are inhabited by a finite number of named values which may carry additional associated information, and can have properties and methods attached to them.
 
-### Defining Enums
+## Defining Enums
 
 The most basic enums are defined as seen below.
 
@@ -27,15 +29,15 @@ enum NESButton {
 
 This defines a new type named `NESButtons` with possible values `up`, `down`, `left`, `right`, `a`, `b`, `select`, and `start`. These values can be referred to by following the name of the type with a dot (`.`) and the value. In cases where the type name can be inferred, only the dot and value are needed.
 
-### Methods
+## Methods
 
 Like other types in Swift, enums may contain methods which allow the enum to provide functionality based on the current value of the enum.
 
 Methods are analogous to functions, only they are defined inside the body of the enum and they are tied to the current enum value. They are accessed via _dot notation_ where the name of the enum value is followed by a dot (`.`) and the name of the method and its parameters.
 
 Inside the method, the enum value can be referred to as `self`, and in the type signature, if one is accepting as a parameter or returning a value of the the enum they can refer to the type as `Self`.
 
-#### Initializers
+### Initializers
 
 Initializers are special methods that are used to set up a value of the enum. Their definition looks a lot like that of a method only there is no `func` keyword, no return type, and the name must be `init` and the initializer _must_ assign a value of the enum to `self`. Initializers are called either via dot notation or by passing the initializer's parameters to the name of the enum.
 

concepts/escaping-functions/about.md

@@ -1,4 +1,6 @@
-### Escaping functions
+# About
+
+## Escaping functions
 
 There are times that a higher-order function takes another function as a parameter and uses it in a way that the passed-in function is called _after_ the higher-order function terminates. This is known as escaping the higher-order function, and the passed-in function is referred to as an [escaping function][escaping].
 

concepts/escaping-functions/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## escaping-functions

concepts/for-loops/about.md

@@ -1,3 +1,5 @@
+# About
+
 [For-in loops][for-in-loops] are used to iterate over a sequence of values, taking each element in turn, binding it to a variable or constant name of the developer's choosing, then executes a block of code that may refer to the element. When every element of the sequence has been iterated over, the loop exits and execution begins with the first line following the body of the loop.
 
 ```swift

concepts/for-loops/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## loops

concepts/function-overloading/about.md

@@ -1,4 +1,4 @@
-## Function overloading
+# Function overloading
 
 We have seen in the Lasagna exercise how functions in Swift are defined using the `func` keyword followed by parentheses enclosed list of parameter names where these names include an optional argument label and a parameter name followed by a type annotation and the body of the function enclosed in curly braces. E.g.
 

concepts/function-overloading/introduction.md

@@ -1,3 +1,5 @@
+# Introduction
+
 TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction
 
 ## function-overloading

concepts/functions/about.md

@@ -1,3 +1,5 @@
+# About
+
 In Swift, [functions][functions] are also values that are associated with names, though the syntax used to declare a function differs from that used to declare a constant or a variable. They are defined using the `func` keyword followed by a pair of parentheses enclosing a comma-separated list of parameter names where these names include an [argument label and a parameter name][argument labels] followed by a [type annotation][type annotations]. The argument label is used to refer to a parameter when the function is _called_ and the parameter name is used to refer to the parameter's value inside the function body. The parameter list is followed by `->` and the type of the value returned by the function. Note that the type annotations for the parameters are required and can not be inferred by the compiler. If the return type of the function is `Void`, i.e. `()`, the `-> ()` or `-> Void` may be omitted.
 
 let fifteen = add10(to: 5)