README

README.md

@@ -123,8 +123,8 @@ In order to get help for internal commands:
 : Why build scripts may have advantages over normal scripts.
 - [Script Tutorial](https://github.com/nightroman/Invoke-Build/wiki/Script-Tutorial)
 : Take a look in order to get familiar with build scripts.
-- [01-step-by-step-tutorial](https://github.com/nightroman/Invoke-Build/tree/main/Tasks/01-step-by-step-tutorial)
-: From "Hello world" to featured script.
+- [Step by Step Tutorial](https://github.com/nightroman/Invoke-Build/tree/main/Tasks/01-step-by-step-tutorial)
+: From "Hello world" to featured scripts.
 - [Invoke-Build.template](https://github.com/nightroman/Invoke-Build.template)
 : Create scripts by `dotnet new ib`.
 - [Project Wiki](https://github.com/nightroman/Invoke-Build/wiki)

Tasks/01-step-by-step-tutorial/01-script-and-task/tea.build.ps1

@@ -1,9 +1,9 @@
 <#
 Initial steps:
-	- create a file named like `*.build.ps1`, `tea.build.ps1`
-	- add a task, `boil_water`, at least one is required
+	- create a file named like `*.build.ps1`: `tea.build.ps1`
+	- add a task, at least one is required: `boil_water`
 
-Run the task boil_water:
+Run the task `boil_water`:
 	Invoke-Build
 	Invoke-Build boil_water
 #>

Tasks/01-step-by-step-tutorial/02-add-new-tasks/tea.build.ps1

@@ -8,8 +8,8 @@ Run any task or combinations:
 	Invoke-Build add_sugar
 	Invoke-Build boil_water, add_tea, add_sugar
 
-Issue:
-	- the last command "make tea" is rather verbose for the task
+Issue to solve:
+	- the last command "make tea" is rather verbose for the objective
 #>
 
 task boil_water {

Tasks/01-step-by-step-tutorial/03-dot-and-docs/tea.build.ps1

@@ -1,13 +1,13 @@
 <#
 New features:
-	- the default task `.` is our "make tea"
-	- special comments `# Synopsis:`
+	- the default task `.` is our objective "make tea"
+	- special task comments `# Synopsis:`
 
-Run the default task:
+Run the default task, "make tea":
 	Invoke-Build
 	Invoke-Build .
 
-Show the task list:
+Show the task list with comments:
 	Invoke-Build ?
 #>
 

Tasks/01-step-by-step-tutorial/06-parameters/tea.build.ps1

@@ -3,7 +3,7 @@ New features:
 	- new script parameters with reasonable defaults
 	- tasks `add_tea` and `add_sugar` use parameters
 
-Make default tea:
+Make default tea, one tea bag, no sugar:
 	Invoke-Build
 
 Make stronger tea with one sugar:

Tasks/01-step-by-step-tutorial/07-conditions/tea.build.ps1

@@ -3,7 +3,7 @@ Resolved:
 	- `add_sugar` is invoked for nothing when there is no sugar
 
 New features:
-	- `add_sugar` has a condition, the task is skipped when there is no sugar
+	- `add_sugar` task condition, it runs with one or more sugar
 #>
 
 param(

Tasks/01-step-by-step-tutorial/08-bootstrap/tea.build.ps1

@@ -1,6 +1,6 @@
 <#
 New features:
-	- parameter `$Tasks` and bootstrap block allow running the script directly
+	- parameter `$Tasks` and bootstrap block to run the script directly
 	- InvokeBuild is installed automatically when needed
 
 Run the build script directly:
@@ -11,8 +11,11 @@ But it is still Invoke-Build:
 #>
 
 param(
-	[string[]]$Tasks,
-	[int]$TeaBags = 1,
+	[Parameter(Position=0)]
+	[string[]]$Tasks
+	,
+	[int]$TeaBags = 1
+	,
 	[int]$SugarLumps
 )
 

Tasks/01-step-by-step-tutorial/09-Docker/tea.build.ps1

@@ -1,12 +1,12 @@
 <#
 New features:
-	- new file `implicit.Dockerfile`, does not install InvokeBuild
-	- new file `explicit.Dockerfile`, gets and imports InvokeBuild
-	- new parameter `Docker`, to choose 'implicit', 'explicit'
+	- new file `implicit.Dockerfile` does not install InvokeBuild
+	- new file `explicit.Dockerfile` gets and imports InvokeBuild
+	- new parameter `Docker` to choose 'implicit', 'explicit'
 	- new task `docker` to build the image
-	- and standard documentation comments
+	- PowerShell script help comments
 
-Build and run the Docker image:
+Build the Docker image, then run it:
 	Invoke-Build docker
 	Invoke-Build docker -Docker explicit
 
@@ -34,6 +34,7 @@ See -WhatIf info and script help:
 		Tells how to build the Docker image. Used by `docker`. Values: implicit (default), explicit
 #>
 param(
+	[Parameter(Position=0)]
 	[string[]]$Tasks
 	,
 	[int]$TeaBags = 1

Tasks/01-step-by-step-tutorial/README.md

@@ -1,4 +1,4 @@
-# Step by step tutorial
+# Step by Step Tutorial
 
 Composing build scripts is incremental process, from small to complex, gradually adding tasks and features.
 

Tasks/Direct/README.md

@@ -46,15 +46,20 @@ usual call by `Invoke-Build`.
 
 See the script [my.build.ps1](my.build.ps1) for a working example.
 
-See also the sample [Paket](../Paket) where a directly invokable build script
-is designed for automatic bootstrapping with `Invoke-Build` downloaded as well.
+## Bootstrap InvokeBuild
 
-## Note
+Directly invokable scripts may automatically install `InvokeBuild` when needed.
 
-Make the parameter `Tasks` positional (`[Parameter(Position=0)]`) and keep other parameters named.
-This maintains similarity of parameters used by direct invocation and `Invoke-Build`.
-Task names are often specified with the parameter name omitted (`Tasks` or `Task`).
-Other parameters are usually named.
+See examples:
 
-Also, using the `Parameter` attribute automatically applies `CmdletBinding`.
-As a result, misspelled or not supported parameters cause invocation errors.
+- [08-bootstrap/tea.build.ps1](../01-step-by-step-tutorial/08-bootstrap/tea.build.ps1) - straightforward bootstrapping
+- [Paket/Project.build.ps1](../Paket/Project.build.ps1) - some custom bootstrapping
+
+## Notes
+
+Consider making the parameter `Tasks` positional (`[Parameter(Position=0)]`) and keeping other parameters named.
+This maintains similarity of parameters used by direct invocation and by `Invoke-Build`:
+tasks are specified first, unnamed, then other parameters, all named.
+
+Also, `Parameter` implies `CmdletBinding`, so we may omit `CmdletBinding` if it was used.
+`Parameter` or `CmdletBinding` is recommended for parameter checks on direct invocations.

Tasks/Direct/my.build.ps1

@@ -38,8 +38,7 @@ param(
 
 # call the build engine with this script and return
 if ($MyInvocation.ScriptName -notlike '*Invoke-Build.ps1') {
-	Invoke-Build $Tasks $MyInvocation.MyCommand.Path @PSBoundParameters
-	return
+	return Invoke-Build $Tasks $MyInvocation.MyCommand.Path @PSBoundParameters
 }
 
 # the usual build script