Add examples to readme.md and add doc comments to the fsi files and update release notes

Author: abelbraaksma

README.md

@@ -29,8 +29,8 @@ Latest version [can be installed from Nuget][nuget].
   - [Progress `taskSeq` CE](#progress-taskseq-ce)
   - [Progress and implemented `TaskSeq` module functions](#progress-and-implemented-taskseq-module-functions)
 - [More information](#more-information)
-  - [Futher reading `IAsyncEnumerable`](#futher-reading-iasyncenumerable)
-  - [Futher reading on resumable state machines](#futher-reading-on-resumable-state-machines)
+  - [Further reading `IAsyncEnumerable`](#further-reading-iasyncenumerable)
+  - [Further reading on resumable state machines](#further-reading-on-resumable-state-machines)
   - [Further reading on computation expressions](#further-reading-on-computation-expressions)
 - [Building & testing](#building--testing)
   - [Prerequisites](#prerequisites)
@@ -109,15 +109,25 @@ As package reference in `fsproj` or `csproj` file:
 
 ```f#
 open System.IO
-
 open FSharp.Control
 
 // singleton is fine
-let hello = taskSeq { yield "Hello, World!" }
+let helloTs = taskSeq { yield "Hello, World!" }
+
+// cold-started, that is, delay-executed
+let f() = task {
+    // using toList forces execution of whole sequence
+    let! hello = TaskSeq.toList helloTs  // toList returns a Task<'T list>
+    return List.head hello 
+}
 
 // can be mixed with normal sequences
 let oneToTen = taskSeq { yield! [1..10] }
 
+// can be used with F#'s task and async in a for-loop
+let f() = task { for x in oneToTen do printfn "Number %i" x }
+let g() = async { for x in oneToTen do printfn "Number %i" x }
+
 // returns a delayed sequence of IAsyncEnumerable<string>
 let allFilesAsLines() = taskSeq {
     let files = Directory.EnumerateFiles(@"c:\temp")
@@ -313,14 +323,14 @@ The following is the progress report:
 
 ## More information
 
-### Futher reading `IAsyncEnumerable`
+### Further reading `IAsyncEnumerable`
 
 - A good C#-based introduction [can be found in this blog][8].
 - [An MSDN article][9] written shortly after it was introduced.
 - Converting a `seq` to an `IAsyncEnumerable` [demo gist][10] as an example, though `TaskSeq` contains many more utility functions and uses a slightly different approach.
 - If you're looking for using `IAsyncEnumerable` with `async` and not `task`, the excellent [`AsyncSeq`][11] library should be used. While `TaskSeq` is intended to consume `async` just like `task` does, it won't create an `AsyncSeq` type (at least not yet). If you want classic Async and parallelism, you should get this library instead.
 
-### Futher reading on resumable state machines
+### Further reading on resumable state machines
 
 - A state machine from a monadic perspective in F# [can be found here][12], which works with the pre-F# 6.0 non-resumable internals.
 - The [original RFC for F# 6.0 on resumable state machines][13]

assets/nuget-package-readme.md

@@ -19,8 +19,8 @@ An implementation of [`IAsyncEnumerable<'T>`][3] as a computation expression: `t
   - [Examples](#examples)
   - [`TaskSeq` module functions](#taskseq-module-functions)
 - [More information](#more-information)
-  - [Futher reading `IAsyncEnumerable`](#futher-reading-iasyncenumerable)
-  - [Futher reading on resumable state machines](#futher-reading-on-resumable-state-machines)
+  - [Further reading `IAsyncEnumerable`](#further-reading-iasyncenumerable)
+  - [Further reading on resumable state machines](#further-reading-on-resumable-state-machines)
   - [Further reading on computation expressions](#further-reading-on-computation-expressions)
 
 -----------------------------------------
@@ -47,15 +47,25 @@ for `use` and `use!`, `try-with` and `try-finally` and `while` loops within the
 
 ```f#
 open System.IO
-
 open FSharp.Control
 
 // singleton is fine
-let hello = taskSeq { yield "Hello, World!" }
+let helloTs = taskSeq { yield "Hello, World!" }
+
+// cold-started, that is, delay-executed
+let f() = task {
+    // using toList forces execution of whole sequence
+    let! hello = TaskSeq.toList helloTs  // toList returns a Task<'T list>
+    return List.head hello 
+}
 
 // can be mixed with normal sequences
 let oneToTen = taskSeq { yield! [1..10] }
 
+// can be used with F#'s task and async in a for-loop
+let f() = task { for x in oneToTen do printfn "Number %i" x }
+let g() = async { for x in oneToTen do printfn "Number %i" x }
+
 // returns a delayed sequence of IAsyncEnumerable<string>
 let allFilesAsLines() = taskSeq {
     let files = Directory.EnumerateFiles(@"c:\temp")
@@ -237,14 +247,14 @@ _The motivation for `readOnly` in `Seq` is that a cast from a mutable array or l
 
 ## More information
 
-### Futher reading `IAsyncEnumerable`
+### Further reading `IAsyncEnumerable`
 
 - A good C#-based introduction [can be found in this blog][8].
 - [An MSDN article][9] written shortly after it was introduced.
 - Converting a `seq` to an `IAsyncEnumerable` [demo gist][10] as an example, though `TaskSeq` contains many more utility functions and uses a slightly different approach.
 - If you're looking for using `IAsyncEnumerable` with `async` and not `task`, the excellent [`AsyncSeq`][11] library should be used. While `TaskSeq` is intended to consume `async` just like `task` does, it won't create an `AsyncSeq` type (at least not yet). If you want classic Async and parallelism, you should get this library instead.
 
-### Futher reading on resumable state machines
+### Further reading on resumable state machines
 
 - A state machine from a monadic perspective in F# [can be found here][12], which works with the pre-F# 6.0 non-resumable internals.
 - The [original RFC for F# 6.0 on resumable state machines][13]

src/FSharp.Control.TaskSeq/AsyncExtensions.fsi

@@ -6,5 +6,7 @@ module AsyncExtensions =
 
     type AsyncBuilder with
 
-        /// Iterate over all values of a taskSeq.
+        /// <summary>
+        /// Inside <see cref="async" />, iterate over all values of a <see cref="taskSeq" />.
+        /// </summary>
         member For: source: taskSeq<'T> * action: ('T -> Async<unit>) -> Async<unit>

src/FSharp.Control.TaskSeq/FSharp.Control.TaskSeq.fsproj

@@ -23,10 +23,11 @@ Generates optimized IL code through the new resumable state machines, and comes
     <PackageReadmeFile>nuget-package-readme.md</PackageReadmeFile>
     <PackageReleaseNotes>
       Release notes:
-      0.2.3 (unreleased)
-       - add TaskSeq.singleton, #90 (by @gusty)
-       - improve TaskSeq.empty by not relying on resumable state, #89 (by @gusty)
-       - do not throw exception for unequal lengths in TaskSeq.zip, fixes #32
+      0.3.0 (unreleased)
+       - adds support for 'for .. in ..' with task sequences in F# tasks and async, #75, #93 and #99 (with help from @theangrybyrd)
+       - adds TaskSeq.singleton, #90 (by @gusty)
+       - improves TaskSeq.empty by not relying on resumable state, #89 (by @gusty)
+       - does not throw exceptions anymore for unequal lengths in TaskSeq.zip, fixes #32
       0.2.2
        - removes TaskSeq.toSeqCachedAsync, which was incorrectly named. Use toSeq or toListAsync instead.
        - renames TaskSeq.toSeqCached to TaskSeq.toSeq, which was its actual operational behavior.

src/FSharp.Control.TaskSeq/TaskExtensions.fsi

@@ -8,4 +8,7 @@ module TaskExtensions =
 
     type TaskBuilder with
 
+        /// <summary>
+        /// Inside <see cref="task" />, iterate over all values of a <see cref="taskSeq" />.
+        /// </summary>
         member inline For: source: taskSeq<'T> * body: ('T -> TaskCode<'TOverall, unit>) -> TaskCode<'TOverall, unit>