We Keep Coding

How to include Javadoc in a library JAR?

I'm currently trying to write my first own library. It's just for testing, I want to find out how libraries are written, compiled, distributed and used in order to prepare for some upcoming personal projects.
Yet, what really causes me to wonder, is why exactly my Javadoc isn't compiled with the Library. I know that comments and annotations are not compiled, but for example the JDK (which is basically a huge library) comes with a working doc as well.
I've tried to compile a JAR (libraries aree normally JARs, right?) from not the compile output, but the sources (so I had a JAR of .java files), but this failed to be included in IntelliJ. I could add it as an external library, but neither did it show up in my explorer, not could I import or use any of my classes.
I know there must be a mistake somewhere here, all libraries I've ver used, whether it was Java, C# or whatever else always came with a working documentation (IntelliJ shold show that on mouse hover), and I'd like to know how to correctly build a library that I can share with a team partner, so he just needs to download it, add it as a library in IntelliJ and has all the functionality, but also the documentation.
Thanks to everyone in advance!

Because it isn't needed, and would bloat the file size of the executable. If you have a library in C or C++, the documentation may be bundled in a zip file, but you won't find it in the compiled .so or .dll. One just holds the binary and resources needed for the project. The .jar is equivalent of that- it's the compiled output. Documentation is hosted/downloaded separately.
When you download the JDK, you're not just downloading a giant .jar. It includes other things, like documentation in the download.

I'd like to know how to correctly build a library that I can share with a team partner, so he just needs to download it, add it as a library in IntelliJ and has all the functionality, but also the documentation.
The short answer is that you provide your team partners with your project source code as well as the binaries. They then can configure their IDE (Intellij, NetBeans, Eclipse, whatever) with the location of the source code and the IDE will be able to extract the javadoc comments on the fly and render them as requested.
Sharing the source code also has the additional benefit that your partners can debug their (and your) code better. By themselves, javadocs are rarely sufficient for debugging complicated problems.

Alright, if everyone ever has this probelm again, here's a complete tutorial:
As #Gabe Sechan already said, the Doc is not compiled into the JAR for some valid reasons. Instead, I recommend you to add the following to your JAR:
module compilation output
content of "src" directory / alternatively: module sources
Build --> Artifacts --> All Artifacts.
Now, if you add your library JAR into a project, it will show "Classes" and "Sources" in the right tab, as IntelliJ automatically recognizes you've bundled both into the JAR.
Now, IntelliJ should show your documentation, as it lives within the source files.
If, for some reason, IntelliJ switches from its "fancy" documentation popup to unformatted plain text, proceed as follows:
Navigate to File -> Settings -> Advanced Settings, and in the 5th block, where it says "Documentation Components", just tick everything you find. That's gonna fix it.
Thanks to Gabe Sechan again, your answer helped me to understand what won't work, and finally I've found a way to make it work myself.

How to rename packages and classes programmically?

I have a code base scattered across tens of repositories.
I want to standardize names of packages and classes, but it's too tedious to do it by hand in IDE, since I need a dictionary based renaming across repositories.
Is there a way programmatically rename classes and packages across many repositories?
A similar thing for a different language: https://metacpan.org/pod/App::EditorTools

Eclipse, and just about every other major IDE, can do this rather trivially. Load the project into the IDE (most can read the project if it is built by maven or gradle, just by saying you want to 'import an existing maven java project' or some such, possibly after installation a maven and/or gradle plugin - if it's not a project built by such tools, then just import an existing java project and tell eclipse about where the source files live).
Then, right click the package, pick refactor/rename, rename it, and eclipse (or intellij, or any other major java IDE) will rename the directory, update the package statement in every source file inside it, and will update all imports or any other reference, and will even search for strings that contain that exact name in case you're doing weird reflective shenanigans and tell you that those probably also need to be updated.
It's not quite programmatic, but this sounds like it'll be much easier and faster than actually using e.g. ecj or writing an eclipse app that will run without a user interface to apply these refactor scripts.

Code Coverage Source Annotation with EclEmma

I installed EclEmma for its source annotation abilities relating to code coverage, how it highlights code with various colors based on whether or not that code is hit during execution. I intend to use this information for debugging purposes. The default install adds a "launch with coverage" button, which is what I want. This works perfectly for the entry point into the program; that entire source file gets beautiful coverage information smeared all over it. Unfortunately none of the other project files get the same treatment.
When I go over to the new coverage tab I see my source folder structure and all of my source files are listed along with coverage percentages. This is nice, but I would really like it to add the coverage annotations to my other source files so that I can review code coverage line by line in the rest of my project. Presently even clicking on them in the coverage tab with the percentage sitting directly to the right opens the plain unannotated source file (well, unannotated besides Eclipse's normal annotations for Java code). How can I get EclEmma to add source code coverage information to all of my source files, not just the one containing the point of entry to the program?
I suspect that there is a simple fix that I am missing, but the best I can get from the relevant documentation is how to change the color of the annotations.
For reference I am using Eclipse 4.2.1 for Java development. My EclEmma installation is the one from the Eclipse Marketplace.
Thank you for your time,
-- Techrocket9

For unknown reasons the issue seems to have resolved itself. I can only conclude that the EclEmma does not require alteration to display source annotations for other files, and that a bug in my particular Eclipse install triggered the issue and that the bug was fixed in an Eclipse or EclEmma update.

Keep correctness of Eclipse workspace with continuous integration

IDE misconfiguration is a big source of inefficient time use in our team.
I wanted to know if other teams have tried to check the health of the eclipse workspace with continuous integration.
Eclipse is open source and extensible, and most (all?) of its files are in xml. So it should not be difficult to add a step to continuous integration that checks the health of the workspace, such as no missing Jar files, no errors, etc.
What we have is a separate ant script to do the real builds that go to QA and to the customers. This ant script is run with continuous integration and we have put in place a few simple checks that catch most big showstoppers.
The workspace configuration is a different story and we sometimes detect problems when it's too late (the dev left home).
EDIT: Note that we share our Eclipse config files.

There is some information on building with Eclipse from the command line here.
(Should be a comment, but I can't).

I don't see why you want to do that. Eclipse complains loudly if anything is broken, so leave it to the developer.
What you should consider instead, in my opinion is to write tests that check that everything is as you expect it to in the building process of those builds from source code that the developer has checked in the source repository.
If a build breaks due to a jar is missing in the build, add a check. If a build breaks because it is dependent on a certain feature in the JVM, add a check.
Only ship builds outside of the development team that pass all tests. Those builds that fail, should be fixed by the developer introducing the change that broke the build.

Since you are using Ant, you can create a custom task that verifies the following files against pre-defined ones. If they don't match, report problem:
workspace/.metadata/*.* (whichever configurations you think are important)
workspace/project/.classpath
workspace/project/.project
workspace/project/.settings/*.* (whichever configurations you think are important)
Of course, these files include some hard-coded paths, so you can use regular expressions in the pre-defined files.
If you want to check only simple things like "the project doesn't compile", then just compile the project in the ant script (using the javac task) and see if there are errors.
Another thing - continuous integration should better be IDE-agnostic. I.e. you must have a IDE-less environment (a CI Engine) that compiles the project. Imagine the following:
three developers, one of them accidentally removed a jar from his Eclipse, but the project in the repository is compiling. No need to report problems in that case
one of the developers adds a new jar and commits. The others have not updated. No problems are reported in there workspaces, although after they update, they might get the problem.
That all said, I think you'd better look at Hudson, which is a continuous integration engine. Thus you won't be dependent on IDE settings for your builds.

To check in, or not check in, the entire Eclipse project?

I'm soon going to check in the very first commit of a new Java project. I work with Eclipse Ganymede and a bunch of plug ins are making things a little bit easier.
Previously I've been part of projects where the entire Eclipse project was checked in. It's quite convenient to get the project settings after a check out. However this approach still was not problem free:
I strongly suspect that some Eclipse configuration files would change without user interaction (from when I used Eclipse Europa), making them appear as changed (as they were changed, but not interactively) when it's time to do a commit.
There are settings unique to each development machine as well as settings global for all developers on a project. Keeping these apart was hard.
Sometime if the Eclipse version was different from others Eclipse would get angry and mess up the project configuration. Another case is that it change the format so it gets updated, and if commited messes up the configuration for others.
For this specific project I have another reason not to commit the project files:
There might be developers who prefer NetBeans which will join the project later. However they won't join within the coming months.
How do you organize this? What do you check into versioning control and what do you keep outside? What do you consider best practice in this kind of situation?

At a minimum you should be check-in the .project and .classpath files. If anybody on your team is hard-coding an external JAR location in the .classpath you should put them up against the wall and shoot them. I use Maven to manage my dependencies but if you are not using maven you should create user libraries for your external JARs with with a consistent naming convention.
After that you need to consider things on a plug-in by plug-in basis. For example I work with Spring so I always check-in the .springBeans and likewise for CheckStyle I always check-in the .checkstyle project.
It gets a bit trickier when it comes to the configuration in the .settings folder but I generally check-in the following if I change the default settings for my project and want them shared with the rest of the team:
.settings/org.eclipse.jdt.ui.prefs - it contains the settings for the import ordering
.settings/org.eclipse.jdt.core.prefs - it contains the settings for the compiler version
In general I haven't noticed Ganymede modifying files without me modifying the project preferences.

I recommend to use maven so that the entire life cycle is outside of any IDE. You can easily create an eclipse project with it on the command line and you can use whatever you want, if it's not eclipse. It has it's quirks but takes out a lot of bitterness when it comes to dependencies and build management.

In our world, we check in the entire Eclipse project and the entire parallel but separate Netbeans project. Our motivations for this were entirely focused on "when I do a checkout, I want a functional configuration immediately afterward." This means that we had to do some work:
Create runnable configurations for each primary IDE (people like what they like). This includes main class, working directory, VM parameters, etc.
Create useful start up scripts for all of our relevant scenarios.
Create edited datasets that don't cause the checkout to take too much longer (it's a big project).
This philosophy was worth cash money (or at least labor hours which are almost more valuable) when our new hire was able to check out the project from Subversion into Eclipse and immediately run a functional system with a (small) real data set without any fuss or bother on his part.
Follow up: this philosophy of "make the new guy's life easier" paid off again when he changed IDEs (he decided to try Netbeans after using Eclipse for quite a long time and decided to stick with it for a while). No configuration was required at all, he just opened the Netbeans project in the same directory that Eclipse had been pointing to. Elapsed switchover time: approximately 60 seconds.

I only ever check in things are done by humans, anything else that is generated (whether automaticly or not) should be easy to regenerate again and is liable to change (as you've stated). The only exeption to this is when the generated files are hard (requires alot of human intervention ;) ) to get it right. How ever things like this should really be automated some how.

Try to port your project to a build system like maven. It has everything you need to get the same experience of the project on every machine you use.
There are plugins for just everything. Like the eclipse plugin. You just type "mvn eclipse:eclipse" and the plugin generates your entire ready to work eclipse project.
To give the answer to your question. Never check in files that are not being used by your project at any time in the development cycle. That means that metadata files like eclipse properties etc. should never be checked in in a SCM.

I like checking in the .project, .classpath, and similar files only if they will be identical on any Eclipse user's machine anyway. (People using other IDEs should be able to check out and build your project regardless, but that issue is orthogonal to whether or not to check in Eclipse-only files.)
If different users working on the project will want to make changes or tweaks to their .project or .classpath or other files, I recommend that you do not check them into source control. It will only cause headaches in the long run.

I use IntelliJ, which has XML project files. I don't check those in, because they change frequently and are easy to recreate if I need to.
I don't check in JAR files. I keep those in a separate repository, a la Maven 2.
I don't check in WARs or JARs or javadocs or anything else that can be generated.
I do check in SQL and scripts and Java source and XML config.

I'd suggest having the actual project files ignored by the version control system due to the downsides you mentioned.
If there is enough consistent information in the project settings that there would be benefit from having it accessible, copy it to a location that Eclipse doesn't treat as special, and you'll have it available to work with on checkout (and copy back to where Eclipse will pay attention to it). There is a decent chance that keeping the actual project files separate from the controlled ones will result in loss of synch, so I'd only suggest this if there is clear benefit from having the settings available (or you're confident that you'll be able to keep them synchronised)

In our case, we used to check in the project files (.project and .classpath) to make it easy for all developers to create their project workspace. A common preferences file and team project set were located in source control as well, so creating your workspace was as simple as import preferences and import team project set. This worked very well, but does rely on everyone having a consistent environment, any customizations would have to be applied after the basic workspace is created.
We still do this for the most part, but Maven is now used so of course dependency management is handled via Maven instead. To avoid conflicting information, the .project and .classpath were removed from source control and are now generated via maven goals before we import the team project set. This would easily allow for different environments, as you would simply need scripts to generate the IDE specific portions based on the Maven configuration.
PS-For ease of maintenance though, I prefer having everyone use the same environment. Anything else inevitably becomes a full time maintenance job for someone.

Netbeans 6.5 has an improved Eclipse project import which is supposed to sync changes from Netbeans back to Eclipse: http://wiki.netbeans.org/NewAndNoteWorthyNB65#section-NewAndNoteWorthyNB65-EclipseProjectImportAndSynchronization

Don't. Only check in the source code of your projects.

As a response to:
"There are settings unique to each development machine as well as settings global for all developers on a project. Keeping these apart was hard."
Eclipse offers a number of ways to keep local settings manageable: Java Classpath Variables (Java > Build Path > Classpath Variables) are one, 'Linked Resources' (General > Workspace > Linked Resources) are another http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.platform.doc.user/concepts/concepts-13.htm Creating a README that states which settings to set before building/running the project works pretty well in my opinion.
Now how to make sure your continuous build system understands the changes that were made to the eclipse settings, thats another issue... (I have a separate build.xml for ant that I keep up to date by hand)