Have you looked at the behavior of libmodulemd with regards to output? It doesn't support comments, however it does enforce the ordering and indentation of the rest of the content in a human-understandable way. (Specifically, it guarantees that the ordering matches the specification).

If this patch is intended to resolve https://pagure.io/modularity/fedmod/issue/8, I think it may be redundant at this point.

My main concern was the unreadable ordering, which moving to libmodulemd would fix. Tried that (will file a PR once someone reviews #69) - seems to basically work. One thing is a bit harder is that when I added auto-generated description metadata based on the RPM description, as a hack I did:

    description:>
        {{ mmd.description|indent(8) }}

I took the the literal RPM description, wrapped as in the RPM metadata, indented it, and let the yaml rules unwrap paragraphs.... a hack, but leaves the yaml file and the result both pretty readable for normal RPM descriptions, and the module maintainer could fine tune. Getting the same result here will be harder - will require unwrapping the description in the fedmod code, or libyaml will escape the embedded newlines in the RPM description and produce an unreadable mess.

Original:

data:
  api:
    rpms:
    - eog
  components:
    rpms:
      eog:
        buildorder: 10
        rationale: Package in api
  dependencies:
    buildrequires:
      platform: f28
    requires:
      platform: f28
  description: Module auto-generated by fedmod
  license:
    module:
    - MIT
  summary: Generated module for eog
document: modulemd
version: 1

Jinja2 template:

document: modulemd
version: 1
data:
    summary: Generated module for eog
    description:>
        Module auto-generated by fedmod
    license:
        module:
        - MIT
    api:
        rpms:
        - eog
    dependencies:
        buildrequires:
            platform: f28
        requires:
            platform: f28
    components:
        rpms:
            eog:
                buildorder: 10
                rationale: Package in api

libmodulemd:

---
document: modulemd
version: 2
data:
  summary: Generated module for eog
  description: >-
    Module auto-generated by fedmod
  license:
    module:
    - MIT
  dependencies:
  - buildrequires:
      platform: [f28]
    requires:
      platform: [f28]
  api:
    rpms:
    - eog
  components:
    rpms:
      eog:
        rationale: Package in api
        buildorder: 10
...

My main concern was the unreadable ordering, which moving to libmodulemd would fix. Tried that (will file a PR once someone reviews #69) - seems to basically work. One thing is a bit harder is that when I added auto-generated description metadata based on the RPM description, as a hack I did:
description:>
{{ mmd.description|indent(8) }}

I took the the literal RPM description, wrapped as in the RPM metadata, indented it, and let the yaml rules unwrap paragraphs.... a hack, but leaves the yaml file and the result both pretty readable for normal RPM descriptions, and the module maintainer could fine tune. Getting the same result here will be harder - will require unwrapping the description in the fedmod code, or libyaml will escape the embedded newlines in the RPM description and produce an unreadable mess.

Could you post an example of this? It shouldn't escape the newlines and if it does, I made a mistake on the format for the description field, which I can fix. Right now the emitter uses YAML_FOLDED_SCALAR_STYLE (which is what was used in the spec.yaml) and that has the effect of turning newlines into spaces, but I could switch it to YAML_LITERAL_SCALAR_STYLE which would preserve the newlines.

See http://www.yaml.org/spec/1.2/spec.html#id2760844 for all the ways scalars can be represented.

libmodulemd is doing exactly what it's asked to - it's just preventing my hack from working - as it should.

data:
  summary: Eye of GNOME image viewer
  description: >-
    The Eye of GNOME image viewer (eog) is the official image viewer for the
    GNOME desktop. It can view single image files in a variety of formats, as
    well as large image collections.
    eog is extensible through a plugin system.

Using the literal style would look better in the file:

data:
  summary: Eye of GNOME image viewer
  description: |-
    The Eye of GNOME image viewer (eog) is the official image viewer for the
    GNOME desktop. It can view single image files in a variety of formats, as
    well as large image collections.
    eog is extensible through a plugin system.

But I think we don't want to say that description fields in modulemd files have random width wrapping in them! - let's take advantage of yaml's flexibility here and leave pre-wrapped descriptions for RPM.

Do we still need this patch when we switch to libmodulemd ? This looks to me like libmodulemd needs just some minor fixes to output yaml with correct indentation and text wrapping.

karsten commented on the pull-request: Use a Jinja2 template to format the output that you are following:
Do we still need this patch when we switch to libmodulemd ? This looks to me like libmodulemd needs just some minor fixes to output yaml with correct indentation and text wrapping.

No, I think libmodulemd is fine without this. Now that you have the f28
update merged, I'll rebase my libmodulemd patch and post a PR for that.

Thanks for the clarification. I'll close this, then.