From f6b1f6bae91b19ea16f49826a1ab3ee443730540 Mon Sep 17 00:00:00 2001
From: Robert Kaussow <mail@thegeeklab.de>
Date: Tue, 12 Apr 2022 22:12:50 +0200
Subject: [PATCH] docs: add instrictions how to use the $ operator (#281)

---
 docs/content/usage/getting-started.md | 15 +++++++++++----
 example/README.md                     | 20 ++++++++++++++++++++
 example/demo-role/defaults/main.yml   |  8 ++++++++
 3 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/docs/content/usage/getting-started.md b/docs/content/usage/getting-started.md
index 6e75513..916c9a8 100644
--- a/docs/content/usage/getting-started.md
+++ b/docs/content/usage/getting-started.md
@@ -12,7 +12,7 @@ ansible-doctor FOLDER
 
 If no folder is passed to _ansible-doctor_, the current working directory is used. The first step is to determine if the specified folder is an Ansible role. This check is very simple and only verifies if there is a sub-directory named `tasks` in the specified folder. After a successful check, _ansible-doctor_ registers all files of the role to search them for annotations.
 
-Without any further work _ansible-doctor_ can already create a documentation of the available variables and some meta information if the role contains [meta information](https://galaxy.ansible.com/docs/contributing/creating_role.html#role-metadata). This basic information can be extended with a set of available annotations.
+Without any further work _ansible-doctor_ can already create a documentation of the available variables and some meta information if the role contains [meta information](https://galaxy.ansible.com/docs/contributing/creating_role.html#role-metadata). This basic information can be extended with a set of available annotations. If you want to see it in action you can find a [demo role](https://github.com/thegeeklab/ansible-doctor/tree/main/example) with a lot of examples in the repository.
 
 ## Annotations
 
@@ -49,10 +49,17 @@ option2
 **Example:**
 
 ```YAML
-# @var docker_registry_password:value: "secure_overwrite"
-# @var docker_registry_password: "secure_overwrite"
+# The `$` operator is required for the `value` option. It's an indicator for the parster to signalize that the `<value>`
+# need to be parsed as JSON. The JSON string is then converted to YAML for the documentation.
+# @var docker_registry_password:value: $ "secure_overwrite"
+# @var docker_registry_password: $ "secure_overwrite"
 
-# @var docker_registry_password:example: "%8gv_5GA?"
+# It's also possible to define more complex values. Keep in mind the `<value>` need to be a valid JSON string.
+# @var docker_registry_insecure: $ ["myregistrydomain.com:5000", "localhost:5000"]
+
+# For the example option, the `$` operator is optional. If it is set, the `<value>` need to be a valid JSON
+# string as described above. If not, the value is passed to the documentation unformatted.
+# @var docker_registry_password:example: $ "%8gv_5GA?"
 
 # @var docker_registry_password:description: Very secure password to login to the docker registry.
 # @var docker_registry_password:description: >
diff --git a/example/README.md b/example/README.md
index 8c07b28..0340624 100644
--- a/example/README.md
+++ b/example/README.md
@@ -12,6 +12,8 @@ Role to demonstrate ansible-doctor. It is also possible to overwrite the default
   - [demo_role_empty](#demo_role_empty)
   - [demo_role_empty_dict](#demo_role_empty_dict)
   - [demo_role_other_tags](#demo_role_other_tags)
+  - [demo_role_override](#demo_role_override)
+  - [demo_role_override_complex](#demo_role_override_complex)
   - [demo_role_single](#demo_role_single)
   - [demo_role_undefined_var](#demo_role_undefined_var)
   - [demo_role_unset](#demo_role_unset)
@@ -97,6 +99,24 @@ demo_role_other_tags:
   - package2
 ```
 
+### demo_role_override
+
+#### Default value
+
+```YAML
+demo_role_override: test
+```
+
+### demo_role_override_complex
+
+#### Default value
+
+```YAML
+demo_role_override_complex:
+  foo: bar
+  second: value
+```
+
 ### demo_role_single
 
 #### Default value
diff --git a/example/demo-role/defaults/main.yml b/example/demo-role/defaults/main.yml
index b2763b2..212fab1 100644
--- a/example/demo-role/defaults/main.yml
+++ b/example/demo-role/defaults/main.yml
@@ -44,3 +44,11 @@ demo_role_dict:
 # ]
 # @end
 demo_role_other_tags: []
+
+## Simple value
+# @var demo_role_override: $ "test"
+demo_role_override: original
+
+## Complex value
+# @var demo_role_override_complex:value: $ {"foo":"bar", "second":"value"}
+demo_role_override_complex: {}