Viral interface documentation idea

[Clint Byrum]

I was chatting with Mark Mims the other day about how to do interface
docs, and we came up with an interesting concept.

We were debating where the docs should live. The wiki will work fine, but
as we all know, these docs will get out of sync with reality relatively
often without super diligent maintenance.

Its not appropriate for the interface docs to live in just one formula,
because there are interfaces which are provided by tons of formulas
already. What to do?

My thought is to have interface documentation be contained in formulas,
and compared in a viral way. As an example:

mysql/interfaces/mysql.yaml:
ensemble: interface
provider:
    description: |
        creates a database, username, and password for related service to access with
        all privileges granted to said user.
    sets:
        user: username to use to connect via mysql protocol
        password: password to use to connect via mysql protocol
        database: database, assume ALL PRIVILEGES
        hostname: hostname to use to connect via mysql protocol
    gets:
        slave: if set to '1', username is granted REPLICATION CLIENT privileges

For anything to use this formula, they do not need to have this file in
their formula, though a warning will be emitted on add-relation or
deploy (or both?):

WARNING: Formula [foo] makes use of interface [mysql] but is missing
interfaces/mysql.yaml, consider copying it from formula [mysql]

On seeing this, the best action to take is to copy the
interfaces/mysql.yaml from the mysql formula. However, its perfectly
appropriate to ignore this and just let your formula go forward w/o
the interface definition.

Then ensemble will hash the two files, and if the hashes match, move
forward. HOWEVER, if the hashes are different, ensemble will stop with
something like:

ERROR: Formulas have different versions of interface [mysql].

Its at this point, that the formula writer who has decided to use mysql
can choose to copy the mysql formula's interface definition. In this way,
they can very easily diff the two interfaces, and make any changes to
their formula necessary. If they feel the new interface is incompatible
with their needs, they can report a bug, and fork the mysql formula,
copying their desired interface into their forked version, or just
removing the interface definition until the problem is fixed.

This way when the mysql formula's interface is changed, it stops working
until all relevant formulas are updated.

The wiki, then, would be generated from the repository's contents. If
multiple interface docs exist for a given interface, all will be put
in the wiki and that will be noted at the top. Something like

"WARNING: this interface has multiple versions, noted below. Please use
caution before selecting an interface for your formula."

Because we want to make diff of the interfaces easy, I think yaml makes
the most sense, but I'm open to even just rst or plain text, though the
yaml would also make sense long term as we find ways to build testing
frameworks around formulas.
 
Thoughts?