Merge pull request #942 from Thorium/doc-fix

Update docs

Author: nojaf

docs/apidocs.fsx

@@ -61,7 +61,7 @@ The HTML is built by instantiating a template. The template used is the first of
 
 * The default template
 
-Usually the same template can be used as for [other content](content.html).
+Usually, the same template can be used as for [other content](content.html).
 
 ## Classic XML Doc Comments
 
@@ -94,7 +94,7 @@ In addition, you may also use the [Recommended XML doc extensions for F# documen
 * `\(...\)` for inline math and `$$...$$` and `\[...\]`for math environments, see http://docs.mathjax.org.
   Some escaping of characters (e.g. `<`, `>`) may be needed to form valid XML
 
-An example of an XML documentation comment, assuming the code is in namespace `TheNamespace`:
+An example of an XML documentation comment, assuming the code is in the namespace `TheNamespace`:
 *)
 /// <summary>
 ///   A module
@@ -211,7 +211,7 @@ If the member cannot be found, a link to the containing module/type will be used
 (**
 ### Classic XMl Doc Comments: Excluding APIs from the docs
 
-If you want to exclude modules or functions from the API docs you can use the `<exclude/>` tag.
+If you want to exclude modules or functions from the API docs, you can use the `<exclude/>` tag.
 It needs to be set on a separate triple-slashed line, and can either appear on its own or as part
 of an existing `<summary>` (for example, you may wish to hide existing documentation while it's in progress).
 The `<exclude/>` tag can be the first or last line in these cases.
@@ -304,16 +304,16 @@ You can do this in two different ways:
 * Add a [markdown inline link](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#links) were the link
 title is the name of the type you want to link.
 
-      /// this will generate a link to [Foo.Bar] documentation
+      /// This will generate a link to [Foo.Bar] documentation
 
 * Add a [Markdown inline code](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) (using
 back-ticks) where the code is the name of the type you want to link.
 
       /// This will also generate a link to `Foo.Bar` documentation
 
 You can use either the full name (including namespace and module) or the simple name of a type.
-If more than one type is found with the same name the link will not be generated.
-If a type with the given name is not found in the same assembly the link will not be generated.
+If more than one type is found with the same name, the link will not be generated.
+If a type with the given name is not found in the same assembly, the link will not be generated.
 *)
 
 /// Contains two types [Bar] and [Foo.Baz]
@@ -353,7 +353,7 @@ module Bar =
     let a = 42
 
 (**
-Example as first line:
+Example as the first line:
 *)
 
 /// [omit]
@@ -366,8 +366,8 @@ module Bar2 =
 
 ## Building library documentation programmatically
 
-You can build library documentation programatically using the functionality
-in the `cref:T:FSharp.Formatting.ApiDocs.ApiDocs` type. To do this, load the assembly and open necessary namespaces:
+You can build library documentation programmatically using the functionality
+in the `cref:T:FSharp.Formatting.ApiDocs.ApiDocs` type. To do this, load the assembly and open the necessary namespaces:
 *)
 
 #r "FSharp.Formatting.ApiDocs.dll"
@@ -414,7 +414,7 @@ ApiDocs.GenerateHtml(
 (**
 or use `libDirs` to include all assemblies from an entire folder.
 Tip: A combination of `<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>` in the fsproj file and setting `libDirs` to the compilation output path leads to only one folder with all dependencies referenced.
-This might be easier especially for large projects with many dependencies.
+This might be easier, especially for large projects with many dependencies.
 *)
 
 ApiDocs.GenerateHtml(
@@ -429,7 +429,7 @@ ApiDocs.GenerateHtml(
 (**
 ## Rebasing Links
 
-The `root` parameter is used for the base of page and image links in the generated documentation. By default it is derived from the project's `<PackageProjectUrl>` property.
+The `root` parameter is used for the base of page and image links in the generated documentation. By default, it is derived from the project's `<PackageProjectUrl>` property.
 
 In some instances, you may wish to override the value for `root` (perhaps for local testing). To do this, you can use the command-line argument `--parameters root <base>`.
 

docs/codeformat.fsx

@@ -33,7 +33,7 @@ This page demonstrates how to use `FSharp.Formatting.CodeFormat` to tokenize
 F# source code, obtain information about the source code (mainly tooltips
 from the type-checker) and how to turn the code into a nicely formatted HTML.
 
-First, we need to load the assembly and open necessary namespaces:
+First, we need to load the assembly and open the necessary namespaces:
 *)
 
 open FSharp.Formatting.CodeFormat
@@ -81,7 +81,7 @@ as those used on [fssnip.net](http://www.fssnip.net) as documented in the
 Working with returned tokens
 ----------------------------
 
-Each returned snippet is essentially just a collection of lines and each line
+Each returned snippet is essentially just a collection of lines, and each line
 consists of a sequence of tokens. The following snippet prints basic information
 about the tokens of our sample snippet:
 *)
@@ -106,8 +106,8 @@ for (Line (_, tokens)) in lines do
 
 (**
 The `TokenSpan.Token` is the most important kind of token. It consists of a kind
-(identifier, keyword, etc.), the original F# code and tool tip information.
-The tool tip is further formatted using a simple document format, but we simply
+(identifier, keyword, etc.), the original F# code and tooltip information.
+The tooltip is further formatted using a simple document format, but we simply
 print the value using the F# pretty printing, so the result looks as follows:
 
     let hello[Literal "val hello : unit -> unit"; ...] () =
@@ -165,6 +165,6 @@ If the input contains multiple snippets separated using the `//[snippet:...]` co
 *)
 
 (**
-then the formatter returns multiple HTML blocks. However, the generated tool tips
+then the formatter returns multiple HTML blocks. However, the generated tooltips
 are shared by all snippets (to save space) and so they are returned separately.
 *)

docs/commandline.md

@@ -30,7 +30,7 @@ The command line options accepted are:
 | `--ignoreprojects`   | Disable project cracking                                                                                                                                                                                                                                                                                                                                                                                        |
 | `--eval`             | Evaluate F# fragments in scripts                                                                                                                                                                                                                                                                                                                                                                                |
 | `--saveimages`       | Save images referenced in docs                                                                                                                                                                                                                                                                                                                                                                                  |
-| `--nolinenumbers`    | Don't add line numbers, default is to add line number.                                                                                                                                                                                                                                                                                                                                                          |
+| `--nolinenumbers`    | Don't add line numbers, the default is to add line numbers.                                                                                                                                                                                                                                                                                                                                                          |
 | `--parameters`       | Additional substitution parameters for templates                                                                                                                                                                                                                                                                                                                                                                |
 | `--nonpublic`        | The tool will also generate documentation for non-public members                                                                                                                                                                                                                                                                                                                                                |
 | `--nodefaultcontent` | Do not copy default content styles, javascript or use default templates                                                                                                                                                                                                                                                                                                                                         |

docs/content.fsx

@@ -60,7 +60,7 @@ Content that is not `*.fsx` or `*.md` is copied across.
 
 ## Default Styling Content
 
-By default additional content such as `fsdocs-search.js`, `fsdocs-tips.js` and `fsdocs-default.css` are included in the
+By default additional content such as `fsdocs-search.js`, `fsdocs-tips.js` and `fsdocs-default.css` are included in 
 the `content` directory of the output.  This can be suppressed with `--nodefaultcontent` or by having your own
 copy of this content in your `content` directory.
 
@@ -70,7 +70,7 @@ Any file or directory beginning with `.` is ignored.
 
 ## Front matter
 
-Each content file can have optional frontmatter.  This determines the navigation bar title, categorization ordering and meta tags.
+Each content file can have an optional frontmatter.  This determines the navigation bar title, categorization ordering and meta tags.
 
 For markdown, the format is:
 ```
@@ -105,7 +105,7 @@ The `keywords` are also used in a meta tag as part of `{{fsdocs-meta-tags}}`. Se
 
 ## Link Translation for Inputs
 
-If an input is used in markdown as a target of a markdown direct link then that is replaced by the output file. For example:
+If an input is used in markdown as a target of a markdown direct link, then that is replaced by the output file. For example:
 
     [Some Text](some-file.md)
 
@@ -212,12 +212,12 @@ buttons to copy out the XmlDoc signature.
 HTML is generated by default. You can also add a `_template.html`.  This should contain `{{fsdocs-content}}`,  `{{fsdocs-tooltips}}`
 and other placeholders. Substitutions are
 applied to this template.
-If a file `_template.html` exists then is used as the template for HTML generation for that directory and all sub-content.
+If a file `_template.html` exists, then it's used as the template for HTML generation for that directory and all sub-content.
 
 ## Generating LaTeX output
 
 To generate .tex output for each script and markdown file, add a `_template.tex`. Substitutions are
-applied to this template. The file is either empty of contains `{{fsdocs-content}}` as the key where the body
+applied to this template. The file is either empty or contains `{{fsdocs-content}}` as the key where the body
 of the document is placed.
 
 ## Generating iPython Notebook output
@@ -233,7 +233,7 @@ in your `docs` directory and use text like this:
 ## Generating Script outputs
 
 To generate .fsx output for each script and markdown file, add a `_template.fsx`, usually empty. Substitutions are
-applied to this template. It is either empty of contains `{{fsdocs-content}}` as the key where the body
+applied to this template. It is either empty or contains `{{fsdocs-content}}` as the key where the body
 of the script is placed.
 
 *)

docs/evaluation.fsx

@@ -58,7 +58,7 @@ To include the meta output of F# Interactive processing such as type signatures
 
     (*** include-fsi-output ***)
 
-To include both console otuput and F# Interactive output blended use `(*** include-fsi-merged-output ***)`.
+To include both console output and F# Interactive output blended use `(*** include-fsi-merged-output ***)`.
 
     let test = 40 + 4
     (*** include-fsi-merged-output ***)
@@ -125,7 +125,7 @@ Literate.ToHtml(doc)
 (**
 When the `fsiEvaluator` parameter is specified, the script is evaluated and so you
 can use additional commands such as `include-value`. When the evaluator is *not* specified,
-it is not created automatically and so the functionality is not available (this way,
+it is not created automatically, so the functionality is not available (this way,
 you won't accidentally run unexpected code!)
 
 If you specify the `fsiEvaluator` parameter, but don't want a specific snippet to be evaluated
@@ -136,14 +136,14 @@ The constructor of `cref:T:FSharp.Formatting.Literate.Evaluation.FsiEvaluator` t
 be used to specify, for example, defined symbols and other attributes for F# Interactive.
 
 You can also subscribe to the `EvaluationFailed` event which is fired whenever the evaluation
-of an expression fails. You can use that to do tests that verify that all off the code in your
+of an expression fails. You can use that to do tests that verify that all of the code in your
 documentation executes without errors.
 
 F# Formatting as a Library: Custom formatting functions
 ---------------------------
 
 As mentioned earlier, values are formatted using a simple `"%A"` formatter by default.
-However, you can specify a formatting function that provides a nicer formatting for values
+However, you can specify a formatting function that provides nicer formatting for values
 of certain types. For example, let's say that we would want to format F# lists such as
 `[1; 2; 3]` as HTML ordered lists `<ol>`.
 
@@ -158,18 +158,18 @@ fsiEvaluator.RegisterTransformation(fun (o, ty, _executionCount) ->
     if ty.IsGenericType
        && ty.GetGenericTypeDefinition() = typedefof<list<_>> then
         let items =
-            // Get items as objects and create paragraph for each item
+            // Get items as objects and create a paragraph for each item
             [ for it in Seq.cast<obj> (unbox o) -> [ Paragraph([ Literal(it.ToString(), None) ], None) ] ]
         // Return option value (success) with ordered list
         Some [ ListBlock(MarkdownListKind.Ordered, items, None) ]
     else
         None)
 (**
 
-The function is called with two arguments - `o` is the value to be formatted and `ty`
+The function is called with two arguments - `o` is the value to be formatted, and `ty`
 is the static type of the value (as inferred by the F# compiler). The sample checks
-that the type of the value is a list (containing values of any type) and then it
-casts all values in the list to `obj` (for simplicity). Then we generate Markdown
+that the type of the value is a list (containing values of any type), and then it
+casts all values in the list to `obj` (for simplicity). Then, we generate Markdown
 blocks representing an ordered list. This means that the code will work for both
 LaTeX and HTML formatting - but if you only need one, you can simply produce HTML and
 embed it in `InlineHtmlBlock`.

docs/literate.fsx

@@ -51,7 +51,7 @@ F# script file with `.fsx` extension. Most of the features should be quite self-
     List.sum numbers
     (*** include-it ***)
 
-The F# script files is processed as follows:
+The F# script files are processed as follows:
 
 - A multi-line comment starting with `(**` and ending with `*)` is
   turned into text and is processed using the F# Markdown processor
@@ -140,7 +140,7 @@ commands. Some of them are demonstrated in the following example:
         Console.WriteLine("Hello world!");
 
 When processing the document, all F# snippets are copied to a separate file that
-is type-checked using the F# compiler (to obtain colours and tool tips).
+is type-checked using the F# compiler (to obtain colours and tooltips).
 The commands are written on the first line of the named snippet, wrapped in `[...]`:
 
  - The `hide` command specifies that the F# snippet should not be included in the
@@ -190,7 +190,7 @@ The LaTeX will also be used in HTML and iPython notebook outputs.
 
 ### Making literate scripts work for different outputs
 
-Literate scripts and markdown can by turned into LaTex, Python Notebooks and F# scripts.
+Literate scripts and markdown can be turned into LaTex, Python Notebooks and F# scripts.
 
 A header may be needed to get the code to load, a typical example is this:
 
@@ -212,9 +212,9 @@ A header may be needed to get the code to load, a typical example is this:
 #endif // IPYNB
 ```
 
-### Processing literate files programatically
+### Processing literate files programmatically
 
-To process file Use the two static methods to turn single documents into HTML
+To process files use the two static methods to turn single documents into HTML
 as follows using functionality from the `cref:T:FSharp.Formatting.Literate.Literate` type:
 *)
 open System.IO
@@ -233,7 +233,7 @@ Literate.ConvertMarkdownFile(doc, template)
 
 (**
 
-The following sample also uses optional parameter `parameters` to specify additional
+The following sample also uses the optional parameter `parameters` to specify additional
 keywords that will be replaced in the template file (this matches the `template-project.html`
 file which is included as a sample in the package):
 *)

docs/markdown.fsx

@@ -28,10 +28,10 @@ Markdown parser
 ==============================
 
 This page demonstrates how to use `FSharp.Formatting.Markdown` to parse a Markdown
-document, process the obtained document representation and
+document, process the obtained document representation, and
 how to turn the code into a nicely formatted HTML.
 
-First, we need to load the assembly and open necessary namespaces:
+First, we need to load the assembly and open the necessary namespaces:
 *)
 
 open FSharp.Formatting.Markdown
@@ -158,7 +158,7 @@ Some span nodes (like emphasis) can contain other formatting, so we need to recu
 process children. This is done by matching against `MarkdownPatterns.SpanNodes` which is an active
 pattern that recognizes any node with children. The library also provides a _function_
 named `MarkdownPatterns.SpanNode` that can be used to reconstruct the same node (when you want
-to transform document). This is similar to how the `ExprShape` module for working with
+to transform a document). This is similar to how the `ExprShape` module for working with
 F# quotations works.
 
 The function `collectParLinks` processes paragraphs - a paragraph cannot directly be a

docs/sidebyside/sideextensions.md

@@ -9,7 +9,7 @@ Example: Using the Markdown Extensions for LaTeX
 
 <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/[email protected]/es5/tex-mml-chtml.js"></script>
 
-To use LaTex extension, you need add javascript
+To use LaTex extension, you need to add javascript
 link to [MathJax](http://www.mathjax.org/) in
 your template or inside a `_head.html` file.
 
@@ -21,7 +21,7 @@ To use inline LaTex, eclose LaTex code with `$`:
 $ k_{n+1} = n^2 + k_n^2 - k_{n-1} $. Alternatively,
 you can also use `$$`.
 
-To use block LaTex, start a new parapgraph, with
+To use block LaTex, start a new paragraph, with
 the first line marked as `$$$` (no close `$$$`):
 
 $$$