TASK: improved docs

Author: Florian Heinze

README.md

@@ -31,30 +31,48 @@ This is how we ended up with the following API to run your tasks.
 `./dev.sh sometask` or `dev sometask`
 
 Some functionality will only be provided by the helper, e.g. running an init. 
-As we do not want to confuse this additional functionality with running a task, we use UPPERCASE arguments for the helper API.
+As we do not want to confuse this additional functionality with running a task, we use UPPERCASE 
+arguments prefixed with `DSR` for utils only provided by the `dev` command.
 
-Example: `dev INIT` to create the files needed in your project.
-
-**You should not use UPPERCASE tasks in your `dev.sh`!**
+Example: `dev DSR_INIT` to create the files needed in your project.
 
 ## Setup
 
 run `brew install sandstorm/tap/dev-script-runner` to install
 
 run `brew upgrade sandstorm/tap/dev-script-runner` to upgrade
 
-Go to your project root and run `dev INIT` to create a `dev.sh` and a `dev_setup.sh` with examples for different types of tasks.
+Go to your project root and run `dev DSR_INIT` to create a `dev.sh` and a `dev_setup.sh` with examples for different types of tasks.
 The `$@` at the end of your `dev.sh` dispatches the script arguments to a function (so `dev sometask` calls `sometask`).
 
 The script is only picked up by the helper if `DEV_SCRIPT_MARKER` is present in the file. 
 
-## Usage
+### Writing tasks
+
+```bash
+# Sometask to help with something
+#
+# The first line of the comment block will be used in the task overview.
+# If you want to provide more details just add more lines ;)
+function sometask() {
+  echo "TODO: implement sometask()"
+}
+```
+
+**Tasks starting with `_` are expected to be private and will be ignored**
 
-`dev <TASK_NAME> [ARGUMENTS]` to run a task
+**You should not use UPPERCASE tasks in your `dev.sh`**
+
+### Documenting Tasks
+
+This currently is WIP and will be improved in the future ;)
+
+## Usage
 
-`dev INIT` to create the files needed in your project
+run `dev` for more information.
 
 ## TODOs
 
 * Autocompletion for tasks
 * Testing
+* more features for documenting tasks -> e.g. support examples, params, ...

cmd/root.go

@@ -18,8 +18,8 @@ DevScriptRunner is a helper to run task from a dev.sh file
 from within a nested folder structure also providing autocompletion
 and other nifty feature ;)
 `,
-	Short:   "SHORT",
-	Example: "",
+	Short:   "run a task of your dev.sh",
+	Example: "run setup",
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.
@@ -31,6 +31,7 @@ func Execute(version, commit string) {
 	addDevScriptTasksAsCommands(RootCmd)
 	RootCmd.AddCommand(buildSectionCommand("utils"))
 	RootCmd.AddCommand(buildInitCommand())
+	// TODO: fix autocompletion
 	// RootCmd.AddCommand(buildCompletionCommand())
 	RootCmd.AddCommand(buildSectionCommand("other"))
 	if err := RootCmd.Execute(); err != nil {

utils/templates/dev.sh

@@ -12,25 +12,25 @@ set -e
 
 ######### TASKS #########
 
-# easy setup of the project
+# Easy setup of the project
 function setup() {
   # As the setup typically is more complex we recommend using a separate shell script
   ./dev_setup.sh
 }
 
-# sometask to help with something
+# Sometask to help with something
 #
-# The first line of the comment will we used in the task overview.
+# The first line of the comment block will be used in the task overview.
 # If you want to provide more details just add more lines ;)
 function sometask() {
   # Most task will only require some steps. We recommend implementing them here
   _log_success "Some task"
   _log_warning "TODO: implement more steps"
 }
 
-# another task to help with something else
+# Another task to help with something else
 #
-# The first line of the comment will we used in the task overview.
+# The first line of the comment block will be used in the task overview.
 # If you want to provide more details just add more lines ;)
 function taskwitharguments() {
   # You can access arguments using $@ array. The task name will not be part of the array