Bug 284650 [CommonNavigator] Misleading JavaDoc of the INavigatorContentService
Build ID: 20090619-0625 Steps To Reproduce: It is stated: "Clients should create instances of the this class using the factory ({@link NavigatorContentServiceFactory}).", which is truth for creation of a new instance only. If the instance of INavigatorContentService is required to configure the existing CNF instance, it should be obtained from the Navigator instead. More information: Here is a chat transcript with Francis Upton: [4:54:09 PM] Simon Zambrovski: NavigatorContentServiceFactory <- this guy is not intended to be used by clients in order to get access to the INavigatorContentService, right? So INavigatorContentService service = new NavigatorContentServiceFactory().createContentService("my.view.id"); is not working, but I should find the view (via IWorkbenchPage.findView()), cast it to the CommonNavigator and finally retrieve the NavigatorContentService from it by calling CommonNavigator.getNavigatorContentService() [4:56:38 PM] Francis Upton: yes [4:56:55 PM] Simon Zambrovski: ok. i'll add this to the wiki, because once you find the INavigatorContentService, its JavaDoc says - use the factory to get an instance of it.... [4:58:39 PM] Francis Upton: the javadoc comments are misleading, it refers to the use of it in a standalone manner which is possible, but not what you want. You want the one assicated with the CN. [4:59:13 PM] Francis Upton: can you file a bug about this? You can copy this transcript into the bug report, and that way I can clean up the doc.
bundles/org.eclipse.ui.navigator/src/org/eclipse/ui/navigator/INavigatorContentService.java
* <p>
 * Clients should create instances of the this class using the factory ({@link NavigatorContentServiceFactory}).
 * </p>
 * 
 * <p>
 * Clients may contribute logical extensions using
 * <b>org.eclipse.ui.navigator.navigatorContent</b>. Each extension has three
 * states which determine whether the extension is used by the content service:
 * <ul>
 * <li><a name="visible"><i>visible</i>: If a content extension id matches a
 * <b>viewerContentBinding</b> for the <i>viewerId</i> of this content
 * service, then the extension is <i>visible</i>. Visible extensions may only
 * be configured through <b>viewerContentBinding</b>s. </li>
 * 
 * <li><a name="active"><i>active</i>: The active state may be set to a default using the
 * <i>activeByDefault</i> attribute of <b>navigatorContent</b>. Users may
 * toggle the <i>active</i> state through the "Available customizations"
 * dialog. Clients may also configure the active extensions using
 * {@link INavigatorActivationService#activateExtensions(String[], boolean)} or
 * {@link INavigatorActivationService#deactivateExtensions(String[], boolean)}
 * from the {@link #getActivationService() Activation Service} </li>
 * 
 * <li><a name="enabled"><i>enabled</i>: An extension is <i>enabled</i> for an element if the
 * extension contributed that element or if the element is described in the
 * <i>triggerPoints</i> element of the <b>navigatorContent</b> extension. The
 * findXXX() methods search for <i>enabled</i> extensions. </li>
 * </ul>
 * </p>
 * <p>
 * A new instance of the content service should be created for each viewer.