Is there any disadvantage to putting API code into a JAR along with the classes?

Question

In Java if you package the source code (.java) files into the jar along with classes (.class) most IDE's like eclipse will show the javadoc comments for code completion.

IIRC there are few open-source projects that do this like JMock.

Lets say I have cleanly separated my API code from implementation code so that I have something like myproject-api.jar and myproject-impl.jar is there any reason why I should not put the source code in my myproject-api.jar ?

Because of Performance? Size?

Why don't other projects do this?

EDIT: Other than the Maven download problem will it hurt anything to put my sources into the classes jar to support as many developers as possible (maven or not)?

Answer 1

Generally because of distribution reason:

if you keep separate binaries and sources, you can download only what you need.
For instance:

• myproject-api.jar and myproject-impl.jar
• myproject-api-src.jar and myproject-impl-src.jar
• myproject-api-docs.zip and myproject-impl-docs.zip

Now, m2eclipse - Maven for Eclipse can download sources automatically as well

mvn eclipse:eclipse -DdownloadSources=true -DdownloadJavadocs=true 

Now, it can also generate the right pom to prevent distribution of the source or javadoc jar when anyone declare a dependency on your jar.
The OP comments:

also can't imagine download size being an issue (i mean it is 2010 a couple 100k should not be a problem).

Well actually it (i.e. "the size) is a problem.
Maven suffers already from the "downloading half the internet on first build" syndrome.
If that downloads also sources and/or javadocs, that begins to be really tiresome.

Plus, the "distribution" aspect includes the deployment: in a webapp server, there is no real advantage to deploy a jar with sources in it.

Finally, if you really need to associate sources with binaries, this SO question on Maven could help.

Answer 2

Using maven, attach the sources automatically like this:

http://maven.apache.org/plugins/maven-source-plugin/usage.html

and the javadocs like this:

http://maven.apache.org/plugins/maven-javadoc-plugin/jar-mojo.html

That way they will automatically be picked up by

mvn eclipse:eclipse -DdownloadSources=true -DdownloadJavadocs=true 

or by m2eclipse