Merge pull request #1370 from dsyme/docs5

update docs

build.cmd

@@ -2,4 +2,4 @@
 
 dotnet tool restore
 dotnet paket restore
-dotnet fake build -t Build
+dotnet fake build  %*

build.fsx

@@ -32,9 +32,9 @@ let project = "FSharp.Data"
 let authors = "Tomas Petricek;Gustavo Guerra;Colin Bull;fsprojects contributors"
 let summary = "Library of F# type providers and data access tools"
 let description = """
-  The FSharp.Data library (FSharp.Data.dll) contains type providers and utilities to access
-  common data formats in your F# applications and scripts. It contains F# type providers for working with
-  structured file formats (CSV, HTML, JSON and XML) and helpers for parsing CSV, HTML and JSON files and for sending HTTP requests."""
+  The FSharp.Data package contains type providers and utilities to access
+  common data formats (CSV, HTML, JSON and XML in your F# applications and scripts. It also
+  contains  helpers for parsing CSV, HTML and JSON files and for sending HTTP requests."""
 let tags = "F# fsharp data typeprovider WorldBank CSV HTML CSS JSON XML HTTP linqpad-samples"
 
 let gitOwner = "fsprojects"

docs/ja/library/CsvFile.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/ja/library/CsvProvider.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/ja/library/Http.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/ja/library/JsonProvider.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/ja/library/JsonValue.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/ja/library/WorldBank.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/ja/library/XmlProvider.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/ja/tutorials/JsonAnonymizer.fsx

@@ -21,7 +21,7 @@ JSON匿名化機能をコード内で利用したい場合には、
 
 *)
 
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 open System
 open System.Globalization
 open FSharp.Data

docs/ja/tutorials/JsonToXml.fsx

@@ -25,7 +25,7 @@ JSONとXML間の変換を自身のコードで使いたい場合には
 *)
 
 #r "System.Xml.Linq.dll"
-#r "../../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 open System.Xml.Linq
 open FSharp.Data
 

docs/library/CsvFile.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/library/CsvProvider.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/library/HtmlCssSelectors.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/library/HtmlParser.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/library/HtmlProvider.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"
@@ -142,7 +142,7 @@ let doctorWho = new HtmlProvider<DrWho>()
 
 // Get the average number of viewers for each doctor's series run
 let viewersByDoctor = 
-  doctorWho.Tables.``Season 13 (1975-1976)``.Rows
+  doctorWho.Tables.``Season 1 (1963-1964) Edit``.Rows
   |> Seq.groupBy (fun season -> season.``Directed by``)
   |> Seq.map (fun (doctor, seasons) -> 
       let averaged = 

docs/library/Http.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/library/JsonProvider.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/library/JsonValue.fsx

@@ -17,7 +17,7 @@ To load a sample JSON document, we first need to reference the `FSharp.Data.dll`
 (when using F# Interactive) or to add reference to a project. 
 *)
 
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 open FSharp.Data
 
 (**

docs/library/WorldBank.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/library/XmlProvider.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/tutorials/JsonAnonymizer.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

docs/tutorials/JsonToXml.fsx

@@ -1,5 +1,5 @@
 (*** condition: prepare ***)
-#r "../../bin/lib/netstandard2.0/FSharp.Data.dll"
+#r "../../src/FSharp.Data/bin/Release/netstandard2.0/FSharp.Data.dll"
 (*** condition: fsx ***)
 #if FSX
 #r "nuget: FSharp.Data,{{fsdocs-package-version}}"

src/CommonProviderImplementation/Helpers.fs

@@ -180,19 +180,25 @@ module internal ProviderHelpers =
             | _ -> None
         | _ -> None
 
+    /// <summary>
     /// Reads a sample parameter for a type provider, detecting if it is a uri and fetching it if needed
-    /// Samples from the web are cached for 30 minutes
+    /// </summary>
+    /// <remarks>
+    /// Samples from the web are cached for 30 minutes. 
     /// Samples from the filesystem are read using shared read, so it works when the file is locked by Excel or similar tools,
+    /// </remarks>
     /// 
-    /// Parameters:
-    /// * valueToBeParsedOrItsUri - the text which can be a sample or an uri for a sample
-    /// * parseFunc - receives the file/url extension (or ""  if not applicable) and the text value 
-    /// * formatName - the description of what is being parsed (for the error message)
-    /// * tp - the type provider
-    /// * cfg - the type provider config
-    /// * resource - when specified, we first try to treat read the sample from an embedded resource
-    ///     (the value specified assembly and resource name e.g. "MyCompany.MyAssembly, some_resource.json")
-    /// * resolutionFolder - if the type provider allows to override the resolutionFolder pass it here
+    /// <param name="valueToBeParsedOrItsUri">the text which can be a sample or an uri for a sample</param>
+    /// <param name="parseFunc">receives the file/url extension (or ""  if not applicable) and the text value </param>
+    /// <param name="formatName">the description of what is being parsed (for the error message)</param>
+    /// <param name="tp">the type provider</param>
+    /// <param name="cfg">the type provider config</param>
+    /// <param name="resource">when specified, we first try to treat read the sample from an embedded resource
+    ///     (the value specified assembly and resource name e.g. "MyCompany.MyAssembly, some_resource.json")</param>
+    /// <param name="resolutionFolder">if the type provider allows to override the resolutionFolder pass it here</param>
+    /// <param name="encodingStr"></param>
+    /// <param name="fullTypeName"></param>
+    /// <param name="maxNumberOfRows"></param>
     let private parseTextAtDesignTime valueToBeParsedOrItsUri parseFunc formatName (tp:DisposableTypeProviderForNamespaces) 
                                       (cfg:TypeProviderConfig) encodingStr resolutionFolder resource fullTypeName maxNumberOfRows =
 
@@ -358,16 +364,16 @@ module internal ProviderHelpers =
     | Schema of string
 
     /// Creates all the constructors for a type provider: (Async)Parse, (Async)Load, (Async)GetSample(s), and default constructor
-    /// * source - the sample/sample list/schema from which the types will be generated
-    /// * getSpec - receives the file/url extension (or ""  if not applicable) and the text value of the sample or schema
-    /// * tp - the type provider
-    /// * cfg - the type provider config
-    /// * encodingStr - the encoding to be used when reading the sample or schema
-    /// * resolutionFolder -> if the type provider allows to override the resolutionFolder pass it here
-    /// * resource - when specified, we first try to treat read the sample from an embedded resource
-    ///     (the value specifies assembly and resource name e.g. "MyCompany.MyAssembly, some_resource.json")
-    /// * fullTypeName - the full name of the type provider, this will be used as the caching key
-    /// * maxNumberOfRows - the max number of rows to read from the sample or schema
+    /// <param name="source">the sample/sample list/schema from which the types will be generated</param>
+    /// <param name="getSpec">receives the file/url extension (or ""  if not applicable) and the text value of the sample or schema</param>
+    /// <param name="tp">the type provider</param>
+    /// <param name="cfg">the type provider config</param>
+    /// <param name="encodingStr">the encoding to be used when reading the sample or schema</param>
+    /// <param name="resolutionFolder -> if the type provider allows to override the resolutionFolder pass it here</param>
+    /// <param name="resource">when specified, we first try to treat read the sample from an embedded resource</param>
+    ///     (the value specifies assembly and resource name e.g. "MyCompany.MyAssembly, some_resource.json")</param>
+    /// <param name="fullTypeName">the full name of the type provider, this will be used as the caching key</param>
+    /// <param name="maxNumberOfRows">the max number of rows to read from the sample or schema</param>
     let generateType formatName source getSpec
                      (tp:DisposableTypeProviderForNamespaces) (cfg:TypeProviderConfig) 
                      encodingStr resolutionFolder resource fullTypeName maxNumberOfRows  =

src/CommonRuntime/NameUtils.fs

@@ -1,4 +1,4 @@
-/// Tools for generating nice member names that follow F# & .NET naming conventions
+/// Tools for generating nice member names that follow F# & .NET naming conventions
 module FSharp.Data.Runtime.NameUtils
 
 open System
@@ -62,7 +62,7 @@ let niceCamelName (s:string) =
     name.[0].ToString().ToLowerInvariant() + name.Substring(1)
   else name
 
-/// Given a function to format names (such as `niceCamelName` or `nicePascalName`)
+/// Given a function to format names (such as 'niceCamelName' or 'nicePascalName')
 /// returns a name generator that never returns duplicate name (by appending an
 /// index to already used names)
 /// 

src/Csv/CsvFile.fs

@@ -1,4 +1,4 @@
-// --------------------------------------------------------------------------------------
+// --------------------------------------------------------------------------------------
 // Untyped CSV api
 // --------------------------------------------------------------------------------------
 
@@ -29,13 +29,15 @@ type CsvRow(parent:CsvFile, columns:string[]) =
   /// Gets a column by name
   member __.Item with get columnName = columns.[parent.GetColumnIndex columnName]
 
-/// Represents a CSV file. The lines are read on demand from `reader`.
-/// Columns are delimited by one of the chars passed by `separators` (defaults to just `,`), and
-/// to escape the separator chars, the `quote` character will be used (defaults to `"`).
-/// If `hasHeaders` is true (the default), the first line read by `reader` will not be considered part of data.
-/// If `ignoreErrors` is true (the default is false), rows with a different number of columns from the header row
+/// <summary>
+/// Represents a CSV file. The lines are read on demand from <c>reader</c>.
+/// Columns are delimited by one of the chars passed by <c>separators</c> (defaults to just <c>,</c>), and
+/// to escape the separator chars, the <c>quote</c> character will be used (defaults to <c>"</c>).
+/// If <c>hasHeaders</c> is true (the default), the first line read by <c>reader</c> will not be considered part of data.
+/// If <c>ignoreErrors</c> is true (the default is false), rows with a different number of columns from the header row
 /// (or the first row if headers are not present) will be ignored.
-/// The first `skipRows` lines will be skipped.
+/// The first <c>skipRows</c> lines will be skipped.
+/// </summary>
 and CsvFile private (readerFunc:Func<TextReader>, [<Optional>] ?separators, [<Optional>] ?quote, [<Optional>] ?hasHeaders, [<Optional>] ?ignoreErrors, [<Optional>] ?skipRows) as this =
   inherit CsvFile<CsvRow>(
     Func<_,_,_>(fun this columns -> CsvRow(this :?> CsvFile, columns)),

src/Csv/CsvInference.fs

@@ -1,4 +1,4 @@
-/// Structural inference for CSV
+/// Structural inference for CSV
 module FSharp.Data.Runtime.CsvInference
 
 open System
@@ -58,8 +58,10 @@ type private SchemaParseResult =
 
 let private asOption = function true, x -> Some x | false, _ -> None
 
+/// <summary>
 /// Parses type specification in the schema for a single column. 
-/// This can be of the form: type|measure|type<measure>
+/// This can be of the form: <c>type|measure|type&lt;measure&gt;</c>
+/// </summary>
 let private parseTypeAndUnit unitsOfMeasureProvider str = 
   let m = typeAndUnitRegex.Value.Match(str)
   if m.Success then
@@ -323,15 +325,16 @@ let internal inferColumnTypes headerNamesAndUnits schema rows inferRows missingV
     ||> getFields preferOptionals
 
 type CsvFile with
+    /// <summary>
     /// Infers the types of the columns of a CSV file
-    /// Parameters:
-    /// * inferRows - Number of rows to use for inference. If this is zero, all rows are used
-    /// * missingValues - The set of strings recogized as missing values
-    /// * cultureInfo - The culture used for parsing numbers and dates
-    /// * schema - Optional column types, in a comma separated list. Valid types are "int", "int64", "bool", "float", "decimal", "date", "timespan", "guid", "string", "int?", "int64?", "bool?", "float?", "decimal?", "date?", "guid?", "int option", "int64 option", "bool option", "float option", "decimal option", "date option", "guid option" and "string option". You can also specify a unit and the name of the column like this: Name (type&lt;unit&gt;). You can also override only the name. If you don't want to specify all the columns, you can specify by name like this: 'ColumnName=type'
-    /// * assumeMissingValues - Assumes all columns can have missing values
-    /// * preferOptionals - when set to true, inference will prefer to use the option type instead of nullable types, double.NaN or "" for missing values
-    /// * unitsOfMeasureProvider - optional function to resolve Units of Measure
+    /// </summary>
+    /// <param name="inferRows"> - Number of rows to use for inference. If this is zero, all rows are used</param>
+    /// <param name="missingValues"> - The set of strings recogized as missing values</param>
+    /// <param name="cultureInfo"> - The culture used for parsing numbers and dates</param>
+    /// <param name="schema"> - Optional column types, in a comma separated list. Valid types are "int", "int64", "bool", "float", "decimal", "date", "timespan", "guid", "string", "int?", "int64?", "bool?", "float?", "decimal?", "date?", "guid?", "int option", "int64 option", "bool option", "float option", "decimal option", "date option", "guid option" and "string option". You can also specify a unit and the name of the column like this: Name (type&lt;unit&gt;). You can also override only the name. If you don't want to specify all the columns, you can specify by name like this: 'ColumnName=type'</param>
+    /// <param name="assumeMissingValues"> - Assumes all columns can have missing values</param>
+    /// <param name="preferOptionals"> - when set to true, inference will prefer to use the option type instead of nullable types, double.NaN or "" for missing values</param>
+    /// <param name="unitsOfMeasureProvider"> - optional function to resolve Units of Measure</param>
     member x.InferColumnTypes(inferRows, missingValues, cultureInfo, schema, assumeMissingValues, preferOptionals, [<Optional>] ?unitsOfMeasureProvider) =
         let unitsOfMeasureProvider = defaultArg unitsOfMeasureProvider defaultUnitsOfMeasureProvider
         let headerNamesAndUnits, schema = parseHeaders x.Headers x.NumberOfColumns schema unitsOfMeasureProvider