1. Added a dependency to my project and built the project -> dependency was downloaded
2. Then I used a class from this dependent library in my source code
3. Pressed Ctrl+Space on this class, and the Javadoc window displayed a message "Javadoc not found. ..." with a link to Attach Javadoc... action
4. This action allows me to either specify a local Javadoc file, or a remote Javadoc URL. But the most relevant and helpful would be if I could download the Javadoc, like I can do from the popup menu of the library under Dependencies node.
The workaround is to cancel the dialog and download the dependency using this popup menu, but this is not discoverable if you don't know about this feature. Having the ability in the Attach Javadoc dialog directly would be more discoverable and convenient.
If there was this option in the dialog, then maybe the link in the doc window could be called "Attach or Download Javadoc...".
Same applies to the Attach Sources... action in the window that displays the synthetic generated source file.
There is an implementation of Source/JavadocAttacher that should be able to automatically download the javadoc/source jar for a given dependency. There are some points of failure that might cause one to miss that feature.
1. We query the maven index either for coordinates (for maven local repo artifacts) or for sha1 hash (otherwise). It fails when the index is not yet read. Well, it doesn't really fail, just return fast empty result or partial result only for some repositories.
2. if there is a remote repository not returning an index, we will reject the attempt prematurely because we are not sure it will grab something
3. we use the currently known repositories to retrieve the artifact. if it fails for some reason, eg. proxy/mirror problem, we report that the attaching has failed to the infrastructure (not sure how that is handled upstream)
4. for central some queries can fail on lucene's BooleanQuery$TooManyClauses but I believe it's not the case of the currently used ones which are not that much general
I've tried and once the indexes are downloaded, the attach javadoc/attach source buttons worked for me. worked == downloaded the relevant artifact and the proper ui appeared showing sources/javadoc
in general the API as is does not scale well for errors/bumps along the way.
A more consistent approach IMHO would be to
1. always show the "attach" dialog
2. inside that dialog let people try maven repository check. If there are errors, fail and show the error, allow retries.
however it's not easily achievable with the current set of APIs AFAIK. All I can do now is to show my own dialog prompting user to retry or cancel which would eventually be followed by the usual dialog(s).
>1. always show the "attach" dialog
>2. inside that dialog let people try maven repository check. If there are
>errors, fail and show the error, allow retries.
The SPI has multiple impls, currently for libraries, platform, maven, fall back.
Each of them requires different UI, always showing some attach dialog does not scale as it will need to be a union of all those impls. The SPI is responsible for showing reasonable UI and feedback to user. The libraries, platform and default impl does it. The maven one does not provide any UI it runs on background and does not handle errors.
(In reply to comment #5)
> >1. always show the "attach" dialog
> >2. inside that dialog let people try maven repository check. If there are
> >errors, fail and show the error, allow retries.
> The SPI has multiple impls, currently for libraries, platform, maven, fall
> Each of them requires different UI, always showing some attach dialog does not
> scale as it will need to be a union of all those impls. The SPI is responsible
> for showing reasonable UI and feedback to user. The libraries, platform and
> default impl does it. The maven one does not provide any UI it runs on
> background and does not handle errors.
well, at what point should I be showing the UI dialog?
Does showing the UI imply I take ownership of the processing? no other dialog is allowed to be shown then? or will we present the user a cascade of dialogs that can all be cancelled until one is chosen?
in the case of maven processing these are the possible turning points
1. index doesn't exist? do we show the user a dialog asking if the index should be downloaded?
2. parts of index are being downloaded? do we show the user UI allowing him to try a partial search and allowing him to wait for the rest of the results?
3. what if no SHA1 match is found for an artifact? we copy& paste the regular "select source jar" UI or just close this dialog and let the other one jump up?
4. what if a1 SHA1 match is found, but the downloading of the source jar is slow or failed? do I show a dialog with progress bar?
At any of these points I could show a dialog for "Maven attaching". Once I show it however, the challenge of what to do when things go wrong arises. Do I just pass the processing to the next guy in line? or do I declare that attaching is not possible and skip all other implementations even though the user likely wanted to the other impl anyway and I just stole the show?
My current thinking is that I implement the maven dialog and wait for the issues described above be filed and let the API owner deal with them then.. :)
alternatively I can just remove the maven (SHA1 index query based) provider and let people just attach javadoc/sources by hand..
reworked ui for 7.4
Integrated into 'main-silver', will be available in build *201307262300* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
User: Milos Kleint <email@example.com>
Log: #215971 reworked default attach dialog allows us to plug into it