The docs need more variety and specificity in function examples

[EzequielBruni]

The problem I've run into when trying to develop themes for Typemill is that I am very much not a programmer. Showing me how a Twig function or loop works with a single example isn't really enough for those of us who have a good handle on HTML/CSS and the like, but have trouble understanding anything more complicated than an if/else statement.

Take this example from the docs:

{% set pagelist = getPageList(navigation, settings.themes.emergency.listpages, base_url) %}
  <ol class="postlist" reversed>
    {% for element in pagelist.folderContent %}
      {% set post = getPageMeta(settings, element) %}
      {% set date = element.order[0:4] ~ '-' ~ element.order[4:2] ~ '-' ~ element.order[6:2] %}
      <li>
         <a href="{{ element.urlAbs }}">{{ post.meta.title }}</a> <time datetime="{{date}}">({{ date | date("d.m.Y") }})</time>
      </li>

    {% endfor %}
  </ol>

That tells me how to make it so I can set a folder in getPageList based on theme settings, and use it to display a folder's contents. But how would I set the folder manually, in the code itself? Is there some sort of page ID that needs to go where settings.themes.emergency.listpages is? How would I use this code to loop through all of my top-level folders to display their contents in a directory-style page?

Failing that, how would I add more details about each page or item to the navigation function, such as the meta description?

Simply put, we need more examples in the documentation, and I'm not smart enough to write them myself.

[EzequielBruni]

Okay, update: I figured out that if you want to outrput the content of a specific folder manually, putting the relative URL in quotes works fine:

{% set pagelist = getPageList(navigation, "/features", base_url) %}
<ul>
  {% for element in pagelist.folderContent %}
    {% set page = getPageMeta(settings, element) %}
    <li>
       <a href="{{ element.urlAbs }}">{{ page.meta.title }}</a>
       <p>{{ page.meta.description|slice(0,80) }}...</p>
    </li>
  {% endfor %}
</ul>

Trying to loop through that with a navigation loop, however, has been only partially successful. This code will correctly render each item's URL and title, but not the meta description:

{% macro loop_over(navigation) %}
    {% import _self as macros %}
    {% for item in navigation %}
        {% if (item.elementType == 'folder') %}
            <h2><a href="{{ item.urlAbs }}">{{ item.name }}</a></h2>
            {% set pagelist = getPageList(navigation, item.urlRel, base_url) %}
            {% if pagelist.contains == "pages" %}
            <ul>
                {% for element in pagelist.folderContent %}
                    {% set page = getPageMeta(settings, element) %}
                    <li>
                        <a href="{{ element.urlAbs }}">
                            <h3>{{ element.name }}</h3>
                        </a>
                        <p>{{ page.meta.description }}</p>
                    </li>
                {% endfor %}
            </ul>
            {% endif %}
        {% else %}
            <h2><a href="{{ item.urlAbs }}">{{ item.name }}</a></h2>
        {% endif %}
    {% endfor %}
{% endmacro %}

{% import _self as macros %}

<ul>
    {{ macros.loop_over(navigation) }}
</ul>