Community
Participate
Working Groups
IActionBarConfigurer - the association between an IActionBarConfigurer and the window it configures is implied only in the call WorkbenchAdvisor.fillActionBars(IWorkbenchWindow, IActionBarConfigurer) yet the doc for IActionBarConfigurer methods often mentions "a window". It's not immediately obvious what window the doc is referring to. Perhaps the method fillActionBars() could drop the IWorkbenchWindow parameter and getWorkbenchWindow() could be added to IActionBarConfigurer. Otherwise, perhaps the doc for each method could have the @see tag that shows what "window" is being referred to.
IWorkbenchConfigurer - is emergencyClosing() the best name for this method? Couldn't it be generalized to "allowUserInput()" ? It is not clear what get/setData() is used for. Arbitrary data? Known constants?
IWorkbenchPreferences - The name is a bit vague, as the issue tag suggests. Perhaps IApplicationPreferences? Also, it's not clear when an application developer would set these preferences from the doc of this class alone, although the doc of WorkbenchAdvisor helps.Will changing them after a window has been created change the behaviour of that window? This could be assumed - much of the workbench reacts to preference changes on the fly.
IWorkbenchWindowConfigurer - the first @see tag refers to a non existing method. The @link elements in getShowCoolBar(), getShowStatusLine(), getShowPerspectiveBar() and getShowFastViewBars() are not actual links because you use a '.' instead of a '#' to seperate class from constant name. Also, the second link attribute should be qualified by IWorkbenchPreferences. Also, the doc doesn't specify if these methods can be used before and/or after the window has been created. getInitialSize() has been changed recently to be 1024x768 - the doc still reads 800x600. Should configureEditorAreaDropListener() be setEditorAreaDropListener()? Can this method be used more than once in the advisor? createMenuBar()/createCoolBarControl()/createStatusLineControl()/createPageComposite() refer to a method createWindowContents... where is this method located? It's not referenced via a @link tag, simply wrapped in a code block...
WorkbenchAdvisor - the doc for some of the pre/post methods seem redundant. The first sentence of the second paragraph is often a rehash of the first. Should eventLoopIdle() have a disclaimer about doing long-running operations in this method? Also, the reference to IWorkbench.close() should be a @link rather than just a code block. This is the case for postWindowRestore and postWindowCreate as well. The doc for fillActionBars use code blocks for constant references instead of @links getInitialWindowPerspectiveId doesn't say whether or not it may return null. Reference to IWorkbenchWindowConfigurer.createPageComposite in createWindowConstants should be a @link. Several code blocks in the doc for this method should be @links
Overall the doc for individual methods is quite good but I don't get a good sense from it how all of the pieces tie together. The package level documentation could do with a good description of the workbench lifecycle and where various methods are invoked. Maybe a flow chart? It might also be useful to duplicate the code example from WorkbenchAdvisor here.
Thanks Kim, I'll have a look at these issues. Note that we generally do not explicitly state when a parameter or return type is never null -- this is assumed unless it explicitly states that it can accept/return null. E.g. see the Javadoc for IResource.
Re comment #1: I considered adding IActionBarConfigurer.getWindow(), however I've decided to leave it as-is. WorkbenchAdvisor.fillActionBars is somewhat unusual in that the action bars may refer to either the action bars of the window itself, or some other component that simply wants to get a picture of the built-in actions, e.g. the perspective customization dialog. For this reason, I think it's clearer -not- to encapsulate the window, or window configurer, in the action bar configurer. I'll clarify this in the Javadoc, and address the other issues above next week, but I don't see any issues here that require changes to the structure of the API.
IActionBarAdvisor gained a getWindowConfigurer() in 3.1. There are still some minor issues here, but nothing further planned for 3.1.
Reassigning bugs in component areas that are changing ownership.
Closing stale bugs.
