Bugzilla – Full Text Bug Listing
| Summary: | Need an extension to expose plug-in javadoc | ||||||
|---|---|---|---|---|---|---|---|
| Product: | [Eclipse Project] PDE | Reporter: | Frederic Plante <fplante> | ||||
| Component: | UI | Assignee: | PDE-UI-Inbox <pde-ui-inbox> | ||||
| Status: | RESOLVED FIXED | QA Contact: | |||||
| Severity: | normal | ||||||
| Priority: | P3 | CC: | cn, crivet, daniel_megert, dirk_baeumer, dkhodges, eclipse-bugs, ed.burnette, erich_gamma, jeem, jose, lauzon, martinae, oyvind.harboe, patmc, philippe_mulet, stefan.baier, vineet, vladimir | ||||
| Version: | 3.0 | ||||||
| Target Milestone: | 3.2 M1 | ||||||
| Hardware: | PC | ||||||
| OS: | Windows XP | ||||||
| Whiteboard: | |||||||
| Bug Depends on: | |||||||
| Bug Blocks: | 103261 | ||||||
| Attachments: |
|
||||||
|
Description
Frederic Plante
I'm not sure I understand what you want to do with it, could you give more details please. For now, the java doc is gathered into one plugin to be referenced from the help system. The org.eclipse.pde.core.source extension is used by the PDE to associate source files with a plug-in's .jars without user input. The JDT makes use of this information for javadoc hover and debugging for instance. The JDT also allows for the association of javadoc with a .jar. My understnading is that this is used for the "Open External Javadoc" JDT feature. To make use of this feature, users currently have to find and manually make the link form the plug-in's .jars to the plug-in's javadoc. This is not obvious for product users which are generally new to Eclipse development. Having an extension point similar to source, but that exposes javadoc would be useful to avoid such manual steps. Also, if 41421 is fixed, this extension would allow Eclipse based products to expose APIs without the need to provide source files. (needed to leverage the javadoc hovers of the JDT Java editor) *** Bug 29390 has been marked as a duplicate of this bug. *** *** Bug 21587 has been marked as a duplicate of this bug. *** *** Bug 39312 has been marked as a duplicate of this bug. *** Should there be a default location as well as an extension point that allows for location definition? Given abc.jar, if the abcsrc.zip is there it is assumed to be the source zip. If say a certain zip or dir (\doc or \javadoc) was assumed to contain the javadoc, that might be nice a well. Javadoc export defaults to the \doc dir, that seems like a possible choice. Regardless of technique, this function will be very useful for teams that need to share API but not source when building or extending eclipse-based products. This has come up in discussions of late. Jim, Currently, there is no clear/standard way to map plug-ins to the javadoc locations, which is why PDE can't do anything about it and the user has to do it manually. This is tedious and would take a very long time because you have to do it for every single library. We need to come up with guidelines for Eclipse on how to locate the javadoc for a plug-in's library. One idea would be to expand the grammar of the org.eclipse.pde.core.source extension point to allow the specification of a javadoc location as well as a source code location. This decision should be done at the product level, of course. What are your thoughts? It should be possible to provide a way for parties to contribute known locations of plug-in Javadoc. There are, however, a couple of complications: (1) Javadoc may be pooled; for example, the Javadoc for all Platform plug-ins are generated at the same time, and stored in the same place. (2) a Javadoc doc tree may be deep inside a help book. For example, the Platform Java doc tree is at eclipse/plugins/org.eclipse.platform.doc.isv/doc.zip#reference/api/ (I'm don't believe that the existing JDT Javadoc support can handle Javadoc in a zip, much less deep inside one.) One good thing that we can capitalize on is that Javadoc doc trees are self- identifying - the package-list file contains the list of all packages documented in that doc tree. So the basic requirment would be for an extension point to which parties could contribute the locations of Javadoc doc trees relevant to certain plug-ins. Unclear to me how much anyone needs to know exactly which plug-ins are covered. JDT allows to have javadoc documentation in archives. To configure this you would set an URL like 'jar:file:/C:/..../doc.isv_3.0.0/doc.zip!/references/api/' >Unclear to me how much anyone needs to know exactly which plug-ins are
>covered.
It does not have to be done on a per-plugin basis. If the javadoc for all the
plug-ins in a feature are in the same ZIP file, then all we need to do is
declare the location of that one ZIP, and the path inside that ZIP where
reference APIs can be found. We already do the same thing for source code
locations where we declare on source location for all the JDT plug-ins.
The problem is that, currently, the javadoc, when shipped separately, is in a
seemingly arbitrary plug-in. For example, for JDT, it
is "org.eclipse.jdt.doc.isv". So we need a standard way to do this, so that
PDE can find it. Is it always going to be a separate plug-in? If so, where
do we specify that information? in the current pde.core.source extension? do
we create a new extension point?
It may be easier to create a new extension point especially for contributing Javadoc trees for plug-ins. The doc plug-ins that contain a Javadoc doc tree would be free to contribute theirs: - org.eclipse.platform.doc.isv plug-in would contribute doc.zip!/reference/api - org.eclipse.jdt.doc.isv plug-in would contribute doc.zip!/reference/api - org.eclipse.pde.doc.user plug-in would contribute doc.zip!/reference/api Unfortunately, this item will have to be dropped from the 3.0 plan. Too late in the game to introduce a new extension point. *** Bug 66343 has been marked as a duplicate of this bug. *** *** Bug 70300 has been marked as a duplicate of this bug. *** Resurrecting for 3.1 cc Erich because it is on his wish list. *** Bug 73852 has been marked as a duplicate of this bug. *** ok, we have a problem. the PDE classpath computation takes place in org.eclipse.pde.core, which is a non-UI plugin. Therefore, we cannot use JavaUI.setJavadocLocation(...). Martin/Philippe, is there an equivalent function in JDT/Core? where, oh where, is Martiiin? *** Bug 96747 has been marked as a duplicate of this bug. *** Wassim, Javadoc locations are now stored as attributes in a class path entry. So no UI needed anymore. dirk, what are we going to do about imported plugins (both binary and with source)? The javadoc for the libraries of imported plugins will have to be hardcoded into the lib entries of the .classpath file, and it appears as though JDT only supports absolute file URLs. So we can't use the roving ECLIPSE_HOME variable. Javadoc for libraries referenced by the PDE container will work fine of course since the container is dynamic. Tthe javadoc location can currently only be specified for types in archives. For types in source, you would still need jdt.ui API (it is set for the whole project, not per source folder). But opeing external Javadoc for types in source is not so common. At import time of a binary plugin, you would know the location and can use this. This is not a good thing to do if this plugin is shared, but that's usually not the case for binary plugins. All other references should go through the PDE container. Other things I'm not sure about: The location you configure would be an address on the local help server, right? I guess the problem there is just to know the port number. Or maybe it can be set to a location on eclipse.org. This is the best solution if you would use the Javadoc wizard on your source and want all references to other plugins to be annotated with links. I don't need to worry about port numbers, etc. For example, to set the javadoc location for org.eclipse.core.runtime, all I do is point the javadoc location to doc.zip!/reference/api inside the org.eclipse.platform.doc.isv plug-in. Shift-F2 takes care of the rest. Mapping a plug-in to a javadoc location is done via the new org.eclipse.pde.core.javadoc extension point. My question was that for binary imported plug-ins, the javadoc location is going to be a hardcoded absolute file URL in the .classpath file. Is that ok? do we have a better alternative for imported plug-ins? The extension point (org.eclipse.pde.core.javadoc) is in. I will attach the HTML version momentarily as a sneak preview. As suggested in comment 6, we now also have a default location for javadoc, much like we do with source code locations. The default location is 'doc/' at the root of a plug-in. When PDE looks for javadoc for a plug-in, we first look in the default location (doc/). If it's there, we use it. Otherwise, we search through the available org.eclipse.pde.core.javadoc extensions looking for the one that contributes javadoc to this particular plug-in. Created attachment 24660 [details]
javadoc extension point
Marking as fixed. The issue in comment 21 with hardcoded paths in the .classpath file is a current JDT limitation in the javadoc support. Ideally, classpath variables or the like should be supported when specifying the javadoc location, which JDT could then resolve before passing the URL to the Help system. *** Bug 105725 has been marked as a duplicate of this bug. *** *** Bug 107413 has been marked as a duplicate of this bug. *** *** Bug 108561 has been marked as a duplicate of this bug. *** |