docs/Windows: Format and clarify documentation

Author: AndrewSB

docs/Windows.md

@@ -7,7 +7,7 @@ Linux.
 
 Currently there are three supported ways to build Swift for Windows.
 
-1. To cross-compile Swift for Windows from another host Operating System (using
+1. To cross-compile Swift for Windows from another host operating system (using
    `clang`), see [Cross Compiling for Windows](./WindowsCrossCompile.md)
 
 1. To build on Windows using `clang-cl`, see [Building on
@@ -18,7 +18,7 @@ Currently there are three supported ways to build Swift for Windows.
 
 `clang-cl` is recommended over MSVC for building Swift on Windows.
 Although it is possible to build the compiler and the standard library with
-MSVC, and use those built products to compile a Swift program, it won't be
+MSVC to use those built products to compile a Swift program, it won't be
 possible to run the binary without seperately obtaining the Swift runtime. On
 the other hand, `clang-cl` is able to build the runtime, which makes it
 possible to build and run all the components required for Swift natively on
@@ -28,5 +28,5 @@ Windows.
 
 On the [Windows Subsystem for
 Linux](https://docs.microsoft.com/en-us/windows/wsl/about), it's possible to
-build and run Swift in a Linux-like enviroment, on Windows. See [the
-doc](./WindowsSubsystemForLinux.md) for details
+build and run Swift in a Linux-like environment, on Windows. See [Getting
+Started with Swift on Windows](./WindowsSubsystemForLinux.md) for details.

docs/WindowsBuild.md

@@ -22,42 +22,42 @@ Windows.
   manually to build Swift on Windows.
 - Windows support for Swift is a work in progress and may not work on your
   system, but it has been tested.
-- Using the latest Visual Studio version is recommended. Swift may fail to
-  build with older C++ compilers.
+- Using the latest Visual Studio version is recommended (tested with Visual
+  Studio 2017 - Version 15.5.5). Swift may fail to build with older C++ 
+  compilers.
 
 ### 1. Install dependencies
-- Make sure to add Python, CMake and Ninja to your `Path` environment variable
 1. Latest version (2.7.12 tested) of [Python
    2](https://www.python.org/downloads/)
-2. Latest version (3.7.0-rc3 tested) of [CMake](https://cmake.org/download/)
-3. Latest version (1.7.1 tested) of
+1. Latest version (3.7.0-rc3 tested) of [CMake](https://cmake.org/download/)
+1. Latest version (1.7.1 tested) of
    [Ninja](https://github.com/ninja-build/ninja/releases/latest)
-4. Latest version (2015 Update 3 tested) of [Visual
+1. Latest version (2015 Update 3 tested) of [Visual
    Studio](https://www.visualstudio.com/downloads/)
-
-- Make sure to include `Programming Languages|Visual C++` and `Windows and Web
-  Development|Universal Windows App Development|Windows SDK` in your
+- Make sure to include "Programming Languages|Visual C++" and "Windows and Web
+  Development|Universal Windows App Development|Windows SDK" in your
   installation.
+- Make sure to add Python, CMake and Ninja to your `Path` environment variable
 
 ### 2. Clone the repositories
 1. Create a folder to contain all the Swift repositories
-2. `apple/swift-cmark` into a folder named `cmark`
-3. `apple/swift-clang` into a folder named `clang`
-5. `apple/swift-llvm` into a folder named `llvm`
-5. `apple/swift` into a folder named `swift`
+1. Clone `apple/swift-cmark` into a folder named `cmark`
+1. Clone `apple/swift-clang` into a folder named `clang`
+1. Clone `apple/swift-llvm` into a folder named `llvm`
+1. Clone `apple/swift` into a folder named `swift`
 - Currently, other repositories in the Swift project have not been tested and
   may not be supported.
 
 ### 3. Build ICU
 1. Download and extract the [ICU source
 code](http://site.icu-project.org/download) to a folder named `icu` in the same
 directory as the other Swift project repositories.
-2. Open `src/win32/allinone.sln` in Visual Studio.
-3. Make sure to select the correct architecture from the drop-down in Visual
+1. Open `src/win32/allinone.sln` in Visual Studio.
+1. Make sure to select the correct architecture from the drop-down in Visual
 Studio.
-4. Right click on the solution in the Solution Explorer window and select
-`Build Solution`.
-5. When this is done, add the `<icu-source>/bin` folder to your `Path`
+1. Right click on the solution in the Solution Explorer window and select
+"Build Solution".
+1. When this is done, add the `<icu-source>/bin` folder to your `Path`
 environment variable.
 
 ### 4. Get ready
@@ -68,7 +68,7 @@ environment variable.
 ```cmd
 VsDevCmd -arch=amd64
 ```
-If instead, you're compiling for a 32-bit Windows target, adapt the `arch`
+If instead you're compiling for a 32-bit Windows target, adapt the `arch`
 argument to `x86` and run
 ```cmd
 VsDevCmd -arch=x86
@@ -92,8 +92,9 @@ cmake --build "%swift_source_dir%/build/Ninja-DebugAssert/cmark-windows-amd64/"
 
 ### 6. Build LLVM/Clang/Compiler-RT
 - This must be done from within a developer command prompt. LLVM and Clang are
-  large projects so building might take a few hours. Make sure that the build
-  type (e.g. Debug/Release) for LLVM/Clang matches the build type for Swift.
+  large projects, so building might take a few hours. Make sure that the build
+  type (e.g. Debug, Release, RelWithDebInfoAssert) for LLVM/Clang matches the
+  build type for Swift.
 - Optionally, you can omit building compiler-rt by removing all lines referring
   to `compiler-rt` below, which should give faster build times.
 ```cmd
@@ -120,7 +121,7 @@ cmake --build "%swift_source_dir%/build/Ninja-DebugAssert/llvm-windows-amd64"
   two hours depending on your system.
 - You may need to adjust the `SWIFT_WINDOWS_LIB_DIRECTORY` parameter depending on
   your target platform or Windows SDK version.
-- While the commands here use MSVC to build, using clang-cl is recommended (see
+- While the commands here use MSVC to build, using `clang-cl` is recommended (see
   the **Clang-cl** section below).
 ```cmd
 mkdir "%swift_source_dir%/build/Ninja-DebugAssert/swift-windows-amd64/ninja"
@@ -163,7 +164,7 @@ cmake -G "Visual Studio 15" "%swift_source_dir%/swift"^
 ## Clang-cl
 
 Follow the instructions for MSVC, but add the following lines to each CMake
-configuration command. `Clang-cl` 4.0.1 has been tested. You can remove the
+configuration command. `clang-cl` 4.0.1 has been tested. You can remove the
 `SWIFT_BUILD_DYNAMIC_SDK_OVERLAY=FALSE` definition, as overlays are supported
 with `clang-cl`, as it supports modules. The `Z7` flag is required to produce
 PDB files that MSVC's `link.exe` can read and enables proper stack traces.

docs/WindowsCrossCompile.md

@@ -1,10 +1,10 @@
-# Cross-compiling Swift for Windows with `clang`.
+# Cross-compiling Swift for Windows with `clang`
 
 This document describes how to cross compile Swift on Windows on a non-Windows
 host. For more context on the status of Swift on Windows in general, see
-[the Windows doc](./Windows.md)
+[Getting Started with Swift on Windows](./Windows.md)
 
-## 1. Setup Visual Studio Environment Variables
+## 1. Set up Visual Studio environment variables
 Building for Windows requires that the Visual Studio environment variables are
 setup similar to the values on Windows. Currently, the runtime has been tested
 to build against the Windows 10 SDK at revision 10.10.586.
@@ -16,20 +16,20 @@ export UniversalCRTSdkDir=".../Windows Kits/10"
 export VCToolsInstallDir=".../Microsoft Visual Studio/2017/Community"
 ```
 
-## 2. Setup `visualc` and `ucrt` modules
+## 2. Set up the `visualc` and `ucrt` modules
 The `visualc.modulemap` located at
 `swift/stdlib/public/Platform/visualc.modulemap` needs to be copied into
 `${VCToolsInstallDir}/include`. The `ucrt.modulemap` located at
 `swift/stdlib/public/Platform/ucrt.modulemap` needs to be copied into
 `${UniversalCRTSdkDir}/Include/${UCRTVersion}/ucrt`.
 
-## 3. Configure the runtime to be built with the just built clang
-Ensure that we use the tools from the just built LLVM and clang tools to build
-the Windows SDK. You will need to pass a few extra options to cmake via the
-`build-script` invocation to achieve this. You will need to expand out the
-path where llvm-ar and llvm-ranlib are built. These are needed to correctly
+## 3. Configure the runtime to be built with the just built `clang`
+Ensure that we use the tools from the just built LLVM and `clang` tools to 
+build the Windows SDK. You will need to pass a few extra options to cmake via
+the `build-script` invocation to achieve this. You will need to expand out the
+path where `llvm-ar` and `llvm-ranlib` are built. These are needed to correctly
 build the static libraries. Note that cross-compiling will require the use of
-lld. Ensure that lld-link.exe (lld-link) is available to clang via your path.
+`lld`. Ensure that `lld-link.exe` is available to clang via your path.
 Additionally, the ICU headers and libraries need to be provided for the build.
 
 ```bash

docs/WindowsSubsystemForLinux.md

@@ -20,8 +20,8 @@ are identical to the Ubuntu dependencies, with the addition of `make`.
 sudo apt-get install git make cmake ninja-build clang python uuid-dev libicu-dev icu-devtools libbsd-dev libedit-dev libxml2-dev libsqlite3-dev swig libpython-dev libncurses5-dev pkg-config libblocksruntime-dev libcurl4-openssl-dev
 ```
 
-### 3. Upgrade clang
-Install a version of clang with C++ 14 support - the default version of clang
+### 3. Upgrade `clang`
+Install a version of `clang` with C++ 14 support; the default version of `clang`
 on WSL results in linker errors during compilation.
 ```bash
 sudo apt-get install clang-3.6
@@ -30,7 +30,7 @@ sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-3.6
 ```
 
 ### 4. Upgrade CMake
-Install the latest version of CMake - Swift uses new CMake features such as
+Install the latest version of CMake; Swift uses new CMake features such as
 `IN_LIST` and won't build without these features.
 ```bash
 wget http://www.cmake.org/files/v3.6/cmake-3.6.2.tar.gz