On Mon, Aug 17, 2009 at 7:20 PM, Rafael Weinstein<[email protected]> wrote: > We talked a few weeks back about parameter conventions for extension methods > and events. > Our original decision which guided the API as it exists today (and has > largely been followed) was that method parameters are of the following form: > <subject>, <details>, <callback> > where > -<subject> is the entity which is the subject of the operation (tab, window, > pageAction etc...) > -<details> is an object of named parameters which provide additional details > about the request > -<callback> is the function that is called upon completion of the request. > in the case of events, it would be just > <subject>, <details> > for instance > > chrome.tabs.move(4, { index: 4 }, function() { // handle success }); > The two main motivations for this style were > 1) Extensibility of the API. Extending the api would (hopefully) only mean > adding additional property params to <details>, and in particular, avoid > having to put additional parameters *after* the callback. > 2) Avoiding subtle errors arising from extension writers handing objects > into methods that were the result of a previous call. > I just reviewed all of our APIs and there are a small number of calls & > events that deviate from this. They are: > > For the following, one or more scalar arguments are not really the subject > of the call, but arguments to it: > extension.connect(name) > tabs.connect(name) > toolstrip.expand(height, url, callback) > toolstrip.collapse(url, callback) > windows.getAll(populate, callback) > |childIds| should be contained in a <details> object: > bookmarks.onChildrenReordered(id, childIds) > |reply| is an object which contains the pageActionId and another object of > data about the action. This should be flattened: > pageActions[<pageActionId>](reply) > > > I propose that we bring these inline with the original convention as part of > the breaking changes that will land for removing the dev flag. > Additionally, the idea that Erik and I had was to keep the original > conventions and add the following: > -<subject> has to be either a scalar of an array of scalars which would > typically be identifiers. > -any of the three can be omitted from the call, but those that do appear > must appear in order. > This would accomplish some additional flexibility in the apis, for example > removing the unfortunate requirement to pass undefined for optional > <subject> or <detail> arguments . i.e. > chrome.tabs.getSelected(undefined, function() { // }) --> > chrome.tabs.getSelected(function() { // } ) > Anyone else as into being as pedantic as I am?
Sorry for the delay replying. I think this is all good. As Aaron said when we chatted offline, I think we need to have a way to have APIs that are exceptions to the rule. For example, maybe extension.connect or tabs.connect would be exceptions? I think the other examples you found (toolstrip, bookmarks, windows) should all be fixed to follow the pattern. Erik --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Chromium-extensions" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/chromium-extensions?hl=en -~----------~----~----~----~------~----~------~--~---
