Serialise to YAML with comments

[BigBoyBarney]

Parsing / deserialising YAML with comments will throw them away due to libyaml skipping them. However, we could still have comment serialisation, which would be very useful for config files that are intended to be edited by the user.

I propose a new YAML::Field, :comment, for YAML::Serializable.
Example:

struct Config
  include ::YAML::Serializable

  @[YAML::Field(converter: Time::EpochConverter, comment: "Unix time of the last update")]
  property last_update : Time = Time.utc.to_unix

  @[YAML::Field(comment: "Update interval in days")]
  property update_interval : Int32 = 7

  property sources : Array(String) = ["1", "2"]
end

would result in:

---
# Unix time of the last update
last_update: 1734177189
# Update interval in days
update_interval: 7
sources:
- 1
- 2

I think this would fit into the module quite well, and annotations could potentially be used for deserialising as well if it's ever implemented in the future.

[straight-shoota]

I think comments are important. Even for serialization/deserialization. The point of YAML is that it's a very human-friendly format. And thus it's typically used for documents that are supposed to be read and edited by humans, rather than pure data-exchange (there are better data formats for that). Allowing to put comments in generated YAML documents can improve their user experience.

Unfortunately, as mentioned above, libyaml has no support for parsing or emitting comments (yaml/libyaml#42). There might be a clever way to jerry-rig serialization by writing directly to the underlying IO. But I'm not sure if that could safely work. If someone want's to take a look at that, be my guest.
But otherwise I don't think we can do much without upstream support.