Update subheading levels

commonly_proposed.md

@@ -1,12 +1,12 @@
-### Commonly Rejected Changes 
+# Commonly Rejected Changes 
 
 This is a list of changes to the Swift language that are frequently proposed but that are unlikely to be accepted.  If you're interested in pursuing something in this space, please familiarize yourself with the discussions that we have already had.  In order to bring one of these topics up, you'll be expected to add new information to the discussion, not just to say, "I really want this" or "this exists in some other language and I liked it there".
 
 Additionally, proposals for out-of-scope changes will not be scheduled for review. The [readme file](README.md) identifies a list of priorities for the next major release of Swift, and the [proposal review status page](https://apple.github.io/swift-evolution/) includes a list of changes that have been deferred for future discussion because they were deemed to be out of scope at the time of review (in addition to a list of changes proposed and rejected after a formal review).
 
 Several of the discussions below refer to "C family" languages.  This is intended to mean the extended family of languages that resemble C at a syntactic level.  This includes languages like C++, C#, Objective-C, Java, and Javascript.
 
-#### Basic Syntax and Operators
+## Basic Syntax and Operators
 
  * [Replace `{}` brace syntax with Python-style indentation](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151214/003656.html): Surely a polarizing issue, but Swift will not change to use indentation for scoping instead of curly braces.
 
@@ -16,13 +16,13 @@ Several of the discussions below refer to "C family" languages.  This is intende
 
  * [Replace `?:` ternary operator](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151214/002609.html): Definitely magical, but it serves a very important use-case for terse selection of different values.  Proposals for alternatives have been intensely discussed, but none have been "better enough" for it to make sense to diverge from the precedent established by the C family of languages.
 
-#### Strings, Characters, and Collection Types
+## Strings, Characters, and Collection Types
 
  * [Single-quotes `''` for character literals](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151221/003977.html): Swift takes the approach of highly valuing Unicode.  However, there are multiple concepts of a character that could make sense in Unicode, and none is so much more commonly used than the others that it makes sense to privilege them.  We'd rather save single quoted literals for a greater purpose (e.g. non-escaped string literals).
 
  * Make `Array<T>` subscript access return `T?` or `T!` instead of `T`: The current array behavior is [intentional](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151214/002446.html), as it accurately reflects the fact that out-of-bounds array access is a logic error.  Changing the current behavior would slow `Array` accesses to an unacceptable degree. This topic has come up [multiple](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151214/002425.html) times before but is very unlikely to be accepted.
 
-#### Control Flow, Closures, Optional Binding, and Error Handling
+## Control Flow, Closures, Optional Binding, and Error Handling
 
  * [`if/else` and `switch` as expressions](https://lists.swift.org/pipermail/swift-evolution/2015-December/000393.html): These are conceptually interesting things to support, but many of the problems solved by making these into expressions are already solved in Swift in other ways.  Making them expressions introduces significant tradeoffs, and on balance, we haven't found a design that is clearly better than what we have so far.
 
@@ -40,7 +40,7 @@ Several of the discussions below refer to "C family" languages.  This is intende
 
  * [Replace the `do`/`try`/`repeat` keywords with C++-style syntax](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151228/004630.html): Swift's error handling approach is carefully designed to make it obvious to maintainers of code when a call can "throw" an error.  It is intentionally designed to be syntactically similar in some ways, but different in other key ways, to exception handling in other languages.  Its design is a careful balance that favors maintainers of code that uses errors, to make sure someone reading the code understands what can throw.  Before proposing a change to this system, please read the [Error Handling Rationale and Proposal](https://github.com/apple/swift/blob/master/docs/ErrorHandlingRationale.rst) in full to understand why the current design is the way it is, and be ready to explain why your changes would be worth unbalancing this design.
 
-#### Miscellaneous
+## Miscellaneous
 
  * [Use garbage collection (GC) instead of automatic reference counting (ARC)](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160208/009403.html): Mark-and-sweep garbage collection is a well-known technique used in many popular and widely used languages (e.g., Java and JavaScript) and it has the advantage of automatically collecting reference cycles that ARC requires the programmer to reason about.  That said, garbage collection has a [large number of disadvantages](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160208/009422.html) and using it would prevent Swift from successfully targeting a number of systems programming domains.  For example, real-time systems (video or audio processing), deeply embedded controllers, and most kernels find GC to be generally unsuitable.  Further, GC is only efficient when given 3–4× more memory to work with than the process is using at any time, and this tradeoff is not acceptable for Swift.
 

proposals/0027-string-from-code-units.md

@@ -20,7 +20,7 @@ After reading through stdlib source and doing my own testing, this is no wives'
 
 Of course, `fromCString(_:)` isn't a silver bullet; it forces a UTF-8 encoding with a null sentinel, requiring either a copy of the origin buffer or regressing to the much slower character-by-character append path if a terminator needs to be added. This is the case with formats that specify the length up front, or unstructured payloads that use another terminator). It also prevents the string itself from containing the null character. Finally, the `fromCString(_:)` constructor requires a call to `strlen`, even if that's already been calculated in users' code.
 
-# Proposed solution
+## Proposed solution
 
 I'd like to expose an equivalent to `String.Type._fromCodeUnitSequence(_:input:)` as public API:
 

proposals/0056-trailing-closures-in-guard.md

@@ -105,9 +105,7 @@ switch expr among { code }
    has some disadvantages: it takes a new keyword (`then`), it diverges
    unnecessarily from the rest of the C family of languages.
 
--------------------------------------------------------------------------------
-
-# Rationale
+## Rationale
 
 On April 20, 2016, the core team decided to **reject** this
 proposal. The core team felt that the benefits from this change were

proposals/0058-objectivecbridgeable.md

@@ -6,14 +6,14 @@
 * Status: **Deferred**
 * Decision Notes: [Rationale](https://lists.swift.org/pipermail/swift-evolution-announce/2016-April/000095.html)
 
-# Introduction
+## Introduction
 
 Provide an `ObjectiveCBridgeable` protocol that allows a Swift type to control how it is represented in Objective-C by converting into and back from an entirely separate `@objc` type. This frees library authors to create truly native Swift APIs while still supporting Objective-C.
 
 Swift-evolution thread: [\[Idea\] ObjectiveCBridgeable](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160222/011032.html)
 
 
-# Motivation
+## Motivation
 
 There is currently no good way to define a Swift-y API that makes use of generics, enums with associated values, structs, protocols with associated types, and other Swift features while still exposing that API to Objective-C.
 
@@ -31,14 +31,14 @@ Choice #1 is not practical in the real world with ship dates, resulting in most
 
 
 
-# Proposed Solution
+## Proposed Solution
 
 Today you can adopt the private protocol `_ObjectiveCBridgeable` and when a bridged collection (like `Array` <--> `NSArray`) is passed between Swift and Objective-C, Swift will automatically call the appropriate functions to  control the way the type bridges. This allows a Swift type to have a completely different representation in Objective-C.
 
 The solution proposed is to expose a new protocol `ObjectiveCBridgeable` and have the compiler generate the appropriate Objective-C bridging thunks for any function or property of an `@objc` type, not just for values inside collections. 
 
 
-## ObjectiveCBridgeable Protocol
+### ObjectiveCBridgeable Protocol
 
 ```swift
 /// A type adopting `ObjectiveCBridgeable` will be exposed
@@ -121,7 +121,7 @@ public extension ObjectiveCBridgeable {
 }
 ```
 
-# Detailed Design
+## Detailed Design
 
 1. Expose the protocol `ObjectiveCBridgeable`. This protocol will replace the old private protocol `_ObjectiveCBridgeable`.
 2. When generating an Objective-C interface for an `@objc` class type:
@@ -136,7 +136,7 @@ public extension ObjectiveCBridgeable {
 5. The Swift type and `ObjectiveCType` must be defined in the same module. If the `ObjectiveCType` is defined in Objective-C then it must come from the same-named Objective-C module.
 
 
-## Ambiguity and Casting
+### Ambiguity and Casting
 
 The compiler generates automatic thunks only when there is no ambiguity, while explicit casts and bridged collection types always use the protocol implementation.
 
@@ -149,12 +149,12 @@ The compiler generates automatic thunks only when there is no ambiguity, while e
     1. The compiler should emit a diagnostic when it detects two Swift types attempting to bridge to the same `ObjectiveCType`.
 3. An exception to these rules exists for trivially convertable built-in types like `NSInteger` <--> `Int` when specified outside of a bridged collection type. In those cases the compiler will continue the existing behavior, bypassing the `ObjectiveCBridgeable` protocol. The effect is that types like `Int` will not bridge to `NSNumber` unless contained inside a collection type (see `BuiltInBridgeable below`).
 
-## Resiliance
+### Resiliance
 
 Adding or removing conformance to `ObjectiveCBridgeable`, or changing the `ObjectiveCType` is a fragile (breaking) change.
 
 
-## Example
+### Example
 
 Here is an enum with associated values that adopts the protocol and bridges by converting itself into an object representation.
 
@@ -210,25 +210,25 @@ class ObjCFizzer: NSObject {
 ```
 
 
-# Impact on existing code
+## Impact on existing code
 
 None. There are no breaking changes and adoption is opt-in.
 
 
-# Alternatives considered
+## Alternatives considered
 
 The main alternative, as stated above, is not to adopt Swift features that cannot be expressed in Objective-C. 
 
 The less feasible alternative is to provide bridging manually by segmenting methods and properties into `@objc` and `@nonobjc` variants, then manually converting at all the touch points. In practice I don't expect this to be very common due to the painful overhead it imposes. Developers are much more likely to avoid using Swift features (even subconsciously).
 
-## Ambiguity
+### Ambiguity
 
 The idea of allowing multiple Swift types to bridge to the same Objective-C type was discussed. It should technically be possible since the same-module rule wouldn't allow the shape of an imported API to vary based on which modules you imported. The compiler *could* skip generating the thunks in this case and the user would need to provide `@objc` equivalent members that performed casting to resolve the ambiguity.
 
 However there doesn't appear to be a convincing case to support such complex behavior so in the interests of simplicity this proposal keeps this kind of ambiguity an error. It can always be relaxed in the future if desired.
 
 
-## BuiltInBridgeable
+### BuiltInBridgeable
 
 On the mailing list the idea of a protocol to supercede `ObjectiveCBridgeable` for built-in types like `Int` was brought up but not considered essential for this proposal. (The protocol would be decorative only, not having any functions or properties).
 
@@ -237,15 +237,13 @@ These types are special because they bridge differently inside collections vs ou
 This can always be implemented in the future if it is desired.
 
 
-# Future Directions
+## Future Directions
 
-## Conditional Conformance
+### Conditional Conformance
 
 It is intended that when and if Swift 3 adopts conditional protocol conformance that the standard library types such as `Array` and `Dictionary` will declare conditional conformance to `ObjectiveCBridgeable` if their element types are `ObjectiveCBridgeable` (with explicitly declared conformance for built-ins like `Int`).
 
--------------------------------------------------------------------------------
-
-# Rationale
+## Rationale
 
 On April 12, 2016, the core team decided to **defer** this proposal from
 Swift 3. We agree that it would be valuable to give library authors the

proposals/0068-universal-self.md

@@ -58,9 +58,7 @@ Not at this time
 
 Thanks Sean Heber, Kevin Ballard, Joe Groff, Timothy Wood, Brent Royal-Gordon, Andrey Tarantsov, Austin Zheng
 
---------------------------------------------------------------------------------
-
-# Rationale
+## Rationale
 
 On [April 27, 2016](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160425/015977.html), the core team decided to **accept a subset of** this proposal.
 

proposals/0073-noescape-once.md

@@ -181,7 +181,7 @@ This includes (full list to be done):
 Those modifications to standard and core libraries will however be part of
 future proposals.
 
-# Rationale
+## Rationale
 
 On [May 11, 2016](https://lists.swift.org/pipermail/swift-evolution-announce/2016-May/000147.html), the core team decided to **Reject** this proposal for Swift 3.
 

proposals/0074-binary-search.md

@@ -278,6 +278,6 @@ The authors considered a few alternatives to the current proposal:
 
 - `binary_search`: The STL function analogous to the proposed `sortedIndex(of:)` method returns only a Boolean value. We determined that a method returning an optional index was more useful: the `.none` case conveys "not found", and the returned index (when found) provides easy access to the matched element.
 
-# Rationale
+## Rationale
 
 On [May 11, 2016](https://lists.swift.org/pipermail/swift-evolution-announce/2016-May/000148.html), the core team decided to **Reject** this proposal.  The feedback on the proposal was generally positive about the concept of adding binary search functionality, but  negative about the proposal as written, with feedback that it was adding too much complexity to the API.

proposals/0090-remove-dot-self.md

@@ -314,9 +314,9 @@ These are directions we rejected early on in the development of Swift, since
 we felt that maintaining familiarity with C-family languages was worth burning
 some implementation complexity.
 
-# Revision history
+## Revision history
 
-## May 26, 2016
+### May 26, 2016
 
 A previous revision of this proposal offered a default disambiguation rule
 for ambiguous type references without type context:

proposals/0099-conditionclauses.md

@@ -129,9 +129,7 @@ Another version retained commas and where clauses but allowed arbitrary ordering
 
 Another version suggested separating clauses with semicolons and newlines.
 
------------------------------------------
-
-# Rationale
+## Rationale
 
 On June 8, 2016, this proposal was **accepted with revision** for Swift 3.
 There was near unanimous agreement that the Swift 2 grammar was inconsistent