Is there a drawback to putting the API code in the JAR along with the classes?

Question

In Java, if you pack source files (.java) in a jar along with classes (.class), most IDEs like eclipse will display javadoc comments for code completion.

IIRC There are several open source projects that do this like JMock.

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

Due to performance? The size?

Why don't other projects do this?

EDIT: besides the Maven loading problem, will it hurt to put my sources in jar classes to support as many developers as possible (maven or not)?

Answer 1

Generally, due to the reason for the spread:

If you save separate binary files and sources, you can download only what you need.
For example:

• 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

M2eclipse - Maven for Eclipse can now download sources automatically

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

Now it can also generate the correct pom to prevent the source or javadoc jar from spreading when someone declares a dependency on your jar.
OP comments:

also cannot imagine that download size is a problem (I mean that in 2010 a 100k pair should not be a problem).

Well, actually this (i.e. size) is a problem.
Maven already suffers from the "download half the Internet at first build" syndrome.
If it also downloads sources and / or javadocs, it becomes really tedious.

In addition, the “distribution” aspect includes deployment : on a webapp server , there is no real advantage to deploying banners with sources in it .

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

Answer 2

Using maven, automatically attach the sources as follows:

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

and javadocs:

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

Thus, they will be automatically picked up

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

or via m2eclipse