On Tue, Aug 26, 2014 at 3:15 AM, Nick Wellnhofer <[email protected]> wrote:
> I'd like to add the Clownfish C API documentation to our generated Perl > PODs, so developers of Perl extensions can find all the docs in one place. > I'm thinking of creating POD files like Clownfish/Docs/C/VArray.pod for > every Clownfish class. Once the API is mature, this is a great plan! > There are some classes like LockFreeRegistry that shouldn't be exposed, > maybe by marking them private. But we can deal with that later. Hmm. I don't understand this approach to publishing an API. Clownfish is likely to remain in flux for a while yet -- but if we expose a public API, we're making backwards compatibility promises which either constrain our ability to evolve the library, or if we break them, try the patience of our users. Forestalling the publication of an immature API and finishing Clownfish's fundamental design is important enough to me that I've put other projects on hold (including the Apache release policy clarification initiative and the Lucy Book Club). Disappointing my collaborators in those other projects was painful, but it was the right move -- because you've invested so much, Nick, and because I believe that the Clownfish "symbiotic" approach is important in this era of siloed language ecosystems. So please help me to understand where you want to go. Do you want to freeze the API? Do you want to simply break compat later? My priority would be to write Clownfish bindings for Python and Ruby, and optionally Go. Once we finish those, I think we will have understood enough of the challenges of writing a symbiotic object system that we can make nearly optimal engineering compromises. Marvin Humphrey
