Viral interface documentation idea

[Gustavo Niemeyer]

> 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.

We don't have to specify everything.  We just have to specify things
as they become more used and as alternative implementations using the
same interface become available.

> 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?

Agreed.

> My thought is to have interface documentation be contained in formulas,
> and compared in a viral way. As an example:
(...)
>    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?):

That's surely an interesting idea, and it resembles a lot a concept we
debated about, which is based on the idea of "structural typing":

    http://en.wikipedia.org/wiki/Structural_type_system

I'm happy to talk more about it, and perhaps it's a good plan to
implement it.  One of the reasons we didn't was to make interfaces
more lightweight to deal with.  We can discuss more next week.

That said, there's a problem in the proposal as it is which is
intermangling the ideas of documentation and interface typing, as it
solves neither issue properly.

On one hand, the documentation isn't good.  It's not saying that the
MySQL database should be created automatically, it's not giving any
reasoning for that, it's not describing the role of both parties in
the relation, and so on.

On the other hand, the interface is also problematic.  What if you
made a typo in one of these comments, or if we want to introduce an
additional detail regarding the possible way to specify a host (e.g.
ports are actually necessary)?  The interface hasn't changed, but it
has been broken by the documentation improvement.

So, even if we are implementing structural types, we still need good
documentation about the key interfaces, and still need to have
interfaces in a way that enables them to stay compatible when facing
minor changes.

We can catch up about this live next week if you want.

-- 
Gustavo Niemeyer
http://niemeyer.net
http://niemeyer.net/plus
http://niemeyer.net/twitter
http://niemeyer.net/blog

-- I never filed a patent.