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>
 * 
 * @since 3.2
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 * 
 */
public interface INavigatorContentService {
	/**
	 * Create a Content Provider which will use an enhanced delegation model to
	 * locate extension content providers using this content service for each
	 * element in the tree.
	 * 
	 * <p>
	 * The content provider returned will populate the root of the viewer in one
	 * of two ways.
	 * <p>
	 * In the first approach, the content provider will seek out content
	 * extensions which are bound using a <b>viewerContentBinding</b>. If any
	 * of the found <b>viewerContentBindings</b> declare the <i>isRoot</i>
	 * attribute on as true, then that set of extensions will be consulted for
	 * the root elements of the tree. The input of the viewer will be supplied
	 * to each of their {@link IStructuredContentProvider#getElements(Object)}
	 * methods and aggregate the results for the root of the viewer.
	 * </p>
	 * <p>
	 * In the second approach, if no <b>viewerContentBindings</b> declare
	 * <i>isRoot</i> as true, then all matching extensions are consulted based
	 * on their <b>triggerPoints</b> expression in the <b>navigatorContent</b>
	 * extension. Any matching extensions are then consulted via their