Finish user guide for tasks and task parameters

doc/user_guide.md

@@ -204,9 +204,95 @@ The `Rsconscript` file is a Ruby script.
 
 Tasks are the high-level user interface for performing functionality in a build
 script.
+Tasks can create Environments that perform compilation/linking steps.
+Tasks can also execute arbitrary commands or perform any miscellaneous logic.
+
+Tasks can have dependencies, which are specified as names of other tasks that
+should be executed before this task executes.
+
+Tasks can have action blocks.
+When a task is executed, all of its action blocks are called in the order in
+which they were added.
+
+Example:
+
+```ruby
+task "build" do
+  Environment.new do |env|
+    env.Program("^^/proj.elf", glob("src/**/*.c"))
+  end
+end
+
+task "flash", deps: "build" do
+  sh "nrfjprog", "-f", "NRF52", "--program", env.expand_path("^^/proj.elf")
+end
+```
+
+In this example, the `flash` task depends on the `build` task.
+So if the project had not yet been built, and the user executes
+`./rscons flash`, the project would first be built and then flashed to the
+target.
+
+If the `task` method is called again with the name of an already existing task,
+the task is not overwritten, but rather modified.
+Any newly specified dependencies are added to the current dependencies.
+Any action block is appended to the task's list of action blocks to execute
+when the task is executed.
 
 ###> Task Parameters
 
+Tasks can also take parameters.
+Parameters are defined by the build script author, and have default values.
+The user can override parameter values on the command line.
+
+Task parameters are defined by passing a parameter constructed with the Rscons
+`param()` method to the `:params` argument of the `task()` method.
+The signature of the `param` method is:
+
+```ruby
+def param(name, value, takes_arg, description)
+```
+
+For example:
+
+```ruby
+task "build", params: [
+  param("myparam", "defaultvalue", true, "My special parameter"),
+  param("xyz", nil, false, "Enable the xyz feature"),
+] do |task, params|
+  Environment.new do |env|
+    env["CPPDEFINES"] << "SOMEMACRO=#{params["myparam"]}"
+    if params["flag"]
+      env["CPPDEFINES"] << "ENABLE_FEATURE_XYZ"
+    end
+  end
+end
+```
+
+With the above `Rsconscript`, the user could invoke Rscons as:
+
+    ./rscons build --myparam=pvalue --xyz
+
+This would pass in "pvalue" as the value to the "myparam" parameter, and a
+truthy value ("--xyz") as the value of the "xyz" parameter.
+
+As seen above, task parameter values can be accessed within a task's action
+block by using the second parameter (`params`) to the action block.
+Task parameter values can also be accessed with the `Task#[]` method on any
+task object.
+This allows accessing the parameter values of any task object, not just the
+task owning the action block being executed.
+
+Example:
+
+```ruby
+task "one", params: param("flag", nil, false, "Enable a flag")
+
+task "two" do
+  puts "Task one's flag #{Task["one"]["flag"] ? "is" : "is not"} set"
+end
+```
+
 ###> Tasks with Special Meaning
 
 Rscons recognizes special meaning for a few tasks: