8

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)?

Adam Gent
  • 47,843
  • 23
  • 153
  • 203
  • I did have a groovy script that would associate the code jars with the sources jars from maven by editing the Eclipse .classpath . I don't use the Maven plugin but I have to imagine it does this association automatically. – Adam Gent May 22 '10 at 13:59

2 Answers2

6

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.

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • Sure I can see that. But its a pain in the butt to then associate myproject-api.jar myproject-api-src.jar so that you can see the javadoc via code completion. Does the Maven Eclipse plugin do this? – Adam Gent May 22 '10 at 13:55
  • I also can't imagine download size being an issue (i mean it is 2010 a couple 100k should not be a problem). So create the separate jars but have the *-api.jar also have the source. – Adam Gent May 22 '10 at 14:03
  • @Adam: just completed my answer. – VonC May 22 '10 at 15:01
  • Yes I have noticed the maven download hell. Fortunately and unfortunately at my company we use Apache Ivy. The other problem is that many people in the corporate world do not use Maven. Thanks for the answer. – Adam Gent May 23 '10 at 13:00
1

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

Sean Patrick Floyd
  • 292,901
  • 67
  • 465
  • 588
  • Yeah I figured Maven did it because I could have sworn I did it the last time I used it. The only problem is that many companies/groups (sadly including mine) do no use Maven but either use Apache Ivy or just there own jar repo. – Adam Gent May 23 '10 at 13:02
  • really? I haven't had any non-maven clients in about 3 years. but since ivy is "maven compatible", there must be a way to mimic this behavior in ivy – Sean Patrick Floyd May 23 '10 at 18:45
  • You must work with some smart people :) Yeah I wish that were the case for me but both our customers/clients and internal code uses Apache Ant. I have grown to really dislike Ant scripts because of the inconsistency from project to project. – Adam Gent Jun 05 '10 at 13:54
  • I like ant a lot, for things maven can't do. But the consistency of maven is a huge time-saver. So if you want real power, use maven and embed ant or gmaven (groovy) – Sean Patrick Floyd Jun 07 '10 at 08:05