We use YAML to capture a structured description of a large instrument deployment. Comments are absolutely key for us. The YAML is revision controlled in git and annotating it as a document (rather than as data) is a huge benefit.
Tagged YAML allowed us to replace an older system that had ten times as much code. Now, there are far fewer, much warmer code paths, and it's easier to use and far less scary to maintain as a result.
Other markups are not the only alternative to this kind of thing. I expect many developers would reach for a database (SQLite?) as a storage medium. However, keeping our data accessible in plain text has been a huge benefit.