Bug 66275

Cannot reproduce.

I downloaded eBaySDKJava_v1.2.0_b091505.zip and unzipped to "/tmp/eBay SDK for
Java 1.2.0". I made a new lib "ebay" with classpath consisting of the five JARs
in the "lib/" folder, and Javadoc consisting of the "docs/LibRef/" folder. I
made a j2seproject, added the ebay lib to it, and used ApiCall in a new class.
Code completion found Javadoc as expected.

Now I make a module suite. I add a lib wrapper to it with ebaysdkcore.jar. I
added the copied JAR (from release/modules/ext/) to the lib's classpath
definition so it will be associated with the Javadoc too. I add a new module to
the suite and add the ebay wrapper as a dep. I add a class to it and use
ApiCall. Code completion works again as expected.

[BTW when filing bugs please include at least as detailed steps to reproduce as
I provide above.]

Ok, so the step I missed was adding the copied jar to the libary. This is an
ugly workaround. I'll change this to an enhancment request to be able to include
Javadoc when defining library wrapper modules. Certainly this would be of value.

Old Summary was: Module projects do not recognize Javadoc when configured as a
folder in the Library Manager

I'm now requesting that you can add Sources and Javadoc to Library Module
Wrapper projects as you can with standard Libraries.

Probably WONTFIX in its current form, because there are independent plans to
make a position-independent library descriptor, but not for 5.0. Without that,
apisupport could only define its own special format, which is not a good idea I
think.

BTW, not sure why but the workaround does not (stops to) work. It is very hard
to develop agains the 3rd party library if you do not know its API details
(trunk, but probably 5.0u1 as well - did not try 5.0).

Ignore my last comment. I did not use _exactly the same_ jar.

Could be implemented using issue #44035, but it is unlikely I or anyone else
will have time to work on apisupport to do so.

is this the only issue regarding the inability to see javadoc for binaries that are part of the module?
How am I supposed to code against 3rd party libaries in a platform based app?

sounds like a P2 bug, not an enhancement..

As mentioned above, you can associate sources and Javadoc using a separate library for now.

<rant>
"for now" has been almost 3 years already :(
</rant>

I've never felt the problem so far, but since migrating the maven modules to ant from maven, it's been rather painful to
make sense of any of the maven/nexus method calls.

please consider for the 6.next version. Preferably in the same way jar dependencies are handled in j2se projects.

Well, migrating from Maven to Ant is going to be painful no matter what the IDE does because Maven would automatically
give you the sources for such JARs and Ant will not. apisupport.project does not even have a GUI for
<class-path-extension> yet; even if it did, at best you would be able to manually enter a path to sources which would be
stored in nbproject/private/ somewhere. A little easier than creating a library descriptor, but not much better.

it should be at least on par with the j2se project type's support for jar's javadoc. While we don't have that many 3rd
party libs in netbeans IDE itself, I think it's quite common for other products based on the platform. 

Correction: there is a Libraries node now, to which you could add an action like Set Javadoc. Could store location in
private.properties. (BTW we *really* need a common infrastructure for Libraries nodes.)

Can someone reiterate our choices how to workaround this? Preferably with a links to a documentation. There should be a
way if this is only RFE.

I do not see how to fix it by editing <class-path-extension> (#desc11) neither I know how to make a sharable library
descriptor used by apisupport project. If I could put foo-src.jar next to my foo.jar and get sources association
(+javadoc) working I'd be happy.

I've just tried Jesse's workaround described in desc2 and it really works. The critical part is that you have to add
JARs from <lib wrapper>/release/modules/ext on Classpath in Library Manager for this to work. I admit that this really
doesn't fit into team environment.

As there is no work on "position-independent library descriptor" I know of, I'd just allow to put relative paths to
source & javadoc into project.properties of the lib wrapper + added some GUI to support it (e.g. on Sources tab in
Project properties). Sources & javadoc for external clusters are done in similar way, and it seems to work well. Any
comments?

j2seproject etc. do support sharable libraries, e.g. lib/nblibraries.properties. I don't know much about the final API
for this (worked on an early version), so talk to the authors - dkonecny and mkleint IIRC.

Talked to Milos, I guess I got the basic idea. Sharable libraries are useful for libraries consisting of multiple JARs
and many projects using them, which is not a typical use case with lib wrappers - usually only the wrapper will
reference the library directly and our FAQ states that we don't generally recommend putting multiple JARs into single
wrapper (although it is useful at times).

On the other hand J2SE project also allows to add source&javadoc to single JAR the way I described above. So I guess I'd
implement this approach first and see if it suffices or there is demand for shared libraries.

Pushed in core-main #612151d66b5f.

There are two ways now, how to add src & javadoc:

1) Via UI added in issue #66188, go to project Properties -> Libraries -> Wrapped JARs -> Edit

2) Via convention over configuration: just put folder or ZIP named "<JAR name without ext.>-javadoc(.zip)" and/or "<jar
name without ext.>-src(.zip)" next to wrapped JAR and it will be picked up automatically (thanks Milos for the idea)

Style #2 would generally be undesirable if the JAR were in the usual location of release/modules/ext, since you would
end up including src/javadoc in the final app.

jglick: is it? why do we get so much configuration (1 or 2 properties in project.properties and 1 or 2 elements in
project.xml) then if everything gets copied anyway..

mkleint - yes files in release/ are copied to ${cluster} (and registered in the NBM fileset) automatically; nothing else
is required (except <class-path-extension> in project.xml if you indeed wish to add items to Class-Path). See
harness/README. Perhaps you are thinking of release.* properties, which are primarily useful in nb.org sources since we
are required to keep third-party libraries in */external/ dirs. See DevFaqExternalLibraries.

Integrated into 'main-golden', will be available in build *200908311509* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main-golden/rev/612151d66b5f
User: Richard Michalsky <rmichalsky@netbeans.org>
Log: #66275: src & javadoc for lib wrappers