Add some comments describing the macros

[ganto]

These are some suggestions following #363. However, I'm struggling a bit.

• get_realm_yaml_list: I didn't try to figure out what's that for yet
• get_XXXX_version: No idea what they are for
• indent: Already nicely commented, congrats 👍 Would still help to have a short description of the arguments though
• merge_dict: This is a tough one. Couldn't follow all the code paths yet. What is the dict_key for? In which case is this lookup("flattened") used?

[drybjed]

The merge_dict macro does something at bit different - it lets you combine a set of YAML dictionaries and YAML list of dictionaries into one YAML dictionary. If a YAML list is processed, a specific dictionary key in each entry (by default name) is used as the key of the resulting YAML dictionary.

For example, have two variables:

var_dict:

  'some_stuff':
    key1: val1
    key2: val2

var_list:

  - name: 'other_stuff'
    key3: val3
    key4: val4

The result of using merge_dict on these two will be:

var_combined:

  'some_stuff':
    key1: val1
    key2: val2

  'other_stuff':
    key3: val3
    key4: val4

Furthermore, if the macro detects two YAML dictionaries with the same key, they will be combined together, with the latter's keys replacing the former's keys. This can be used to modify the default dictionaries somewhat, for example by changing specific keys. For more extensive changes you still may need to make the default key absent (if the role supports this, which most already do) and redefine the key yourself, since you cannot remove existing keys from a dictionary that way.

I've found that the best use scenario is to have the default variables be YAML dictionaries, and then use YAML lists of dictionaries either in the inventory or role dependent variables which lets you add multiple YAML lists together.

[ganto]

@drybjed Thanks a lot for your explanation. I still haven't fully got the thing with key replacing feature. I guess you better extend the description and examples yourself.

I explicitly wrote the examples more "code"-like that it resembles how someone would write the jinja templates and I didn't want to use too much space. However, the description might be more clear if the dicts are properly indented as in your explanation above. I can still change that if you wish.

I hope you and @ypid now get the idea what I meant with the original request in #363. Would be great if you could maybe merge this and then still add the missing documentation. I think this would help new users understand the code and intention of it much better especially if they are not that native in writing and reading Jinja as you are. At least it already helped a lot for me.

[ypid]

get_XXXX_version

A grep over DebOps roles should give you a hint.