APIs (Re: [Portland] The Plan)

[Bryce Harrington]

On Wed, Mar 01, 2006 at 04:51:02PM +0100, Lubos Lunak wrote:
>  Also, assuming I'm getting right what you said (it seems to me you're talking 
> about documenting the APIs for app developers), that's not what I meant. I'm 
> talking about creating the APIs - what to add and how exactly it should look 
> like. Even out of the 10 calls that I have at least 6 still need changes and 
> are not final (they need a mainwindow they relate to or startup notification 
> info, otherwise they'll be wrong with focus stealing prevention).

No, I understand, not documenting the API for app developers, but rather
pointing to a good example of how to make new API calls.  I.e., pick
what you feel to be the best example of the 10 and point to it as "the
one to copy".  Make sure that one's commented about why you made
particular decisions about e.g. naming conventions, etc.  Nothing too
elaborate; you've probably already got something that suits the bill.

>  Ok, unless somebody has a better idea, let's do this:
> 
> - I have already all calls from the Short Term Tasks from 
> http://freedesktop.org/wiki/PortlandIntegrationTasks that make sense to be 
> calls (installing apps/launcher/mimetype-handler is done by putting .desktop 
> files somewhere and as such it doesn't need API). Plus I have the few more I 
> consider useful.
> 
>  If somebody, preferably some ISV so that we don't add might-be-perhaps-useful 
> stuff, wants something more, be it from the medium/long term tasks or 
> something else, say what you need. And try to be precise. "I want to query 
> the addressbook" is a good start, but it's barely a start.
> 
> - For every call, we need a specification for API.txt that describes the API 
> call precisely including its functionality. I consider what's in API.txt to 
> be sufficient for the calls that are already there. We just need to check if 
> there aren't some problems waiting for or if there isn't something more 
> wanted from the call. As already mentioned many of the calls currently have 
> the problem of missing relation to the application's window. For the 
> LocalFile/UploadFile there it perhaps might be useful to have progress 
> callbacks. This needs to be sorted out.
> 
> - For testing we can mark calls experimental, unsupported, etc. They'll be 
> implemented but they may still change later.
> 
> - After a call is deemed to be okay, it's marked stable, implemented and 
> whatever.

Sounds good.  Have any of the GNOME developers given comments on this so
far?  

Bryce