[skip ci] update README.md and docs

README.md

@@ -163,7 +163,9 @@ Or to get help for subcommands e.g.
 provs-desktop.jar ide -h
 provs-server.jar k3s -h
 ```
+
 ## Development & mirrors
+
 Development happens at: https://repo.prod.meissa.de/meissa/provs
 
 Mirrors are:
@@ -171,3 +173,17 @@ Mirrors are:
 * https://github.com/DomainDrivenArchitecture/provs
 
 For more details about our repository model see: https://repo.prod.meissa.de/meissa/federate-your-repos
+
+## Developer information
+
+For using provs framework, add the required dependency to your project, then you can implement your own tasks e.g. by:
+
+```kotlin
+import org.domaindrivenarchitecture.provs.framework.core.Prov
+
+fun Prov.myCustomTask() = task {
+    cmd("echo \"Hello world!\"")
+}
+```
+
+See also [ForDevelopers.md](doc/ForDevelopers.md)

doc/ForDevelopers.md

@@ -1,22 +1,8 @@
-# Information for developers
+This page provides information for developers.
 
-## Create a provs jar-file
+# Tasks
 
-* Clone this repo
+## What is a task ?
-* Build the jar-file by `./gradlew uberjarDesktop`
-* In folder build/libs you'll find the file `provs-desktop.jar`
-
-This uberjar is a Java jar-file including all required dependencies.
-
-## Task
-
-```kotlin
-fun Prov.provisionK3s() = task { /* ... code and subtasks come here ... */ }
-```
-
-If you're having a deeper look into the provs code, you'll see regularly a task definition like this and might wonder ...
-
-### What is a task ?
 
 A task is the **basic execution unit** in provs. When executed, each task produces exactly one result (line) with either success or failure.
 
@@ -26,9 +12,91 @@ The success or failure is computed automatically in the following way:
 * a task defined with **optional** (i.e. `= optional { /* ... */ }` always returns success (even if there are failing subtasks)
 * **requireLast** defines a task which must provide an explicit result and solely this result counts for success calculation
 
+## Task declaration 
+
+### Recommended way
+
+A task can be declared by 
+
+```kotlin
+fun Prov.myCustomTask() = task { /* ... code and subtasks come here ... */ }
+// e.g.
+fun Prov.myEchoTask() = task { 
+    cmd("echo hello world!") 
+}
+```
+
+The task will succeed if all sub-tasks (called tasks during execution) have succeeded resp. if no sub-task was called.  
+
+### Alternative ways
+
+The following ways are equivalent but are more verbose:
+
+```kotlin
+// Redundant declaration of the return type (ProvResult), which is already declared by task
+fun Prov.myCustomTask(): ProvResult = task { /* ... code and subtasks come here ... */ }
+
+// Redundant parentheses behind task
+fun Prov.myCustomTask() = task() { /* ... code and subtasks come here ... */ }
+
+// Redundant definition of the task name, but could be used to output a different task name  
+fun Prov.myCustomTask() = task("myCustomTask") { /* ... code and subtasks come here ... */ }
+
+// Functionally equal, but with additional curly brackets 
+fun Prov.myCustomTask() { task { /* ... code and subtasks come here ... */ } }
+```
+
+Btw, the following lines are wrong and will not work as expected, as they result in too much lamda nesting:
+```
+fun Prov.myCustomTask() = { task { /* ... code and subtasks come here ... */ } }
+fun Prov.myCustomTask() {{ task { /* ... code and subtasks come here ... */ } }}
+```
+### TaskWithResult
+
+In case you want explicitly to include the return value (of type `ProvResult`) of a task to be added to the evaluation, 
+you need to use `taskWithResult` instead of `task` and return the intended value, e.g. like 
+
+```kotlin
+fun Prov.myEchoTask() = taskWithResult { 
+    cmd("echo hello world!") 
+    // ...
+    ProvResult(false, "Error: ... error message ...")  // will be the returned as return value and included in the evaluation 
+}
+```
+
+IMPORTANT: the value you want to return must be placed at the end of the lambda code (as usual in functional programming)!
+The following will NOT work as expected:
+
+```kotlin
+fun Prov.myEchoTask() = taskWithResult {
+    ProvResult(false, "Error: ... error message ...")  // will be ignored
+    // the result from the call below (i.e. from task "cmd") will be returned by myEchoTask,
+    // which is redundant as its result is already included in the evaluation anyway. 
+    cmd("echo hello world!")  
+}
+```
+
+
+### Task output
+
+If the correctly defined task `myEchoTask` is run e.g. with `local().myEchoTask()`, it will produce output like
+```
+>  Success -- myEchoTask 
+--->  Success -- cmd [/bin/bash, -c, echo hello world!]
+```
+
 
 ## Call hierarchy
 
 In the following link you can find an example of a sequence diagram when provisioning a desktop:
 
 [ProvisionDesktopSequence.md](ProvisionDesktopSequence.md)
+
+
+## Create a provs jar-file
+
+* Clone this repo
+* Build the jar-file by `./gradlew uberjarDesktop`
+* In folder build/libs you'll find the file `provs-desktop.jar`
+
+This uberjar is a Java jar-file including all required dependencies.