This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
Summary: | Generated Javadoc could link to Javadoc of other projects | ||
---|---|---|---|
Product: | java | Reporter: | vbrabant <vbrabant> |
Component: | Javadoc | Assignee: | Jesse Glick <jglick> |
Status: | RESOLVED WONTFIX | ||
Severity: | blocker | CC: | dkonecny |
Priority: | P3 | ||
Version: | 4.x | ||
Hardware: | All | ||
OS: | All | ||
Issue Type: | ENHANCEMENT | Exception Reporter: | |
Bug Depends on: | |||
Bug Blocks: | 41537 |
Description
vbrabant
2004-05-18 11:54:14 UTC
Why UI? Tricky though would probably be possible using ReferenceHelper, if the subproject exported its Javadoc as an artifact. The blocking problem is that when you pass -link to Javadoc you need to give some kind of path (absolute or relative; -linkoffline can have the absolute development-time path), which means the Javadoc links would work only if the HTML were deployed in the same configuration as your sources are in, which is highly unlikely. I.e. for a particular set of projects where you (the user) know how the Javadoc is to be deployed, it is nice to create cross-links. But since the IDE does not have such knowledge, at least for j2seproject's, it cannot even guess. If there were a project type that had a well-defined packaging/deployment mechanism that included Javadoc in a particular place, then it would be feasible for the IDE to assume that links should be created with some particular structure. Or if the javadoc tool had some kind of assembly mechanism to merge built documentation, that would be another matter. In the meantime, for j2seprojects you would need to override the Javadoc target to set up cross-links the way you want them, sorry. In the company I am working, the rule is the following: All sources are in a Version Control Repository. But the Javadoc must be never been put under Version Control. It must be generated by each developper on his pc. So, it means that All Javadocs of the sources I handle are on my PC. For most standard API like JUNIT, LOG4J, ..., the javadocs are available somewhere on our intranet. For me, I will be happy if, at least, you use information given for Libraries. In the Libraries Manager, I have to give informations concerning the classes, the sources, and the javadoc. Why not reuse those information ? By the way, When I ask via NB to generate the javadoc for a project, it knows where html pages will be created. Why not also use that information ? Another question, maybe out of subject: What's the main difference between add jar and add lib ? By Adding a lib, I can add more than one jar. But by adding a jar, I can't say where is the corresponding source nor where is his javadoc. So, imho, the feature ADD JAR is not so usefull. Am I wrong ? Re. "By the way, When I ask via NB to generate the javadoc for a project, it knows where html pages will be created. Why not also use that information?" - as I just explained in the last comment, it *could* use that information. But the links would be usable only on your machine, in the location where the Javadoc was generated. If you published the Javadoc, they would all be broken. Perhaps in your case this does not matter, if you are producing the Javadoc for private use only; but I can imagine any users who wish to distribute or publish the Javadoc would consider it a bug that it is created with links which do not work except on the developer's machine. Better to not produce the links at all in such a case. Re. libs: I think it would be possible to link automatically to Javadoc of libraries. Not easy (harder than to link to subprojects actually, for technical reasons) but possible. Note however that the same problem applies - the links will be useless if the Javadoc is moved anywhere else, since they will refer to the particular location of your libs. Only possible solution I can think of is for each library and project to have an optional property for the "published location" of its Javadoc that should be used to link to. If any users actually figured out what this meant, it would let them give a URL etc. where the live Javadoc will finally go, so that other projects can link to the live URL. However this would work only for absolute publishing locations (e.g. "http://myproj.sf.net/javadoc/") and not for relative links (e.g. "../myotherproj-api/"), so it would not be useful in all cases. Or to punt on the issue of producing durable cross-API links, and provide a checkbox (off by default?) in the project customizer to produce links usable on the local machine only - to please local consumers of the Javadoc, but useless for producing software distributions. Re. Add JAR - quite off topic, please use nbusers. (Quick answer: Add Library is better, but Add JAR is a bit quicker.) |