// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.

[[ugr.ref.javadocs]]
= Javadocs

The details of all the public APIs for UIMA are contained in the API Javadocs.
These are located in the docs/api directory; the top level to open in your browser is called link:api/index.html.

Eclipse supports the ability to attach the Javadocs to your project.
The Javadoc should already be attached to the `uimaj-examples` project, if you followed the setup instructions in the xref:oas.adoc#ugr.ovv.eclipse_setup.example_code[setup guide].
To attach Javadocs to your own Eclipse project, use the following instructions.

[NOTE]
====
As an alternative, you can add the UIMA source to the UIMA binary distribution; if you do this you not only will have the Javadocs automatically available (you can skip the following setup), you will have the ability to step through the UIMA framework code while debugging.
To add the source, follow the instructions as described in the xref:oas.adoc#ugr.ovv.eclipse_setup.adding_source[setup guide].
====

To add the Javadocs, open a project which is referring to the UIMA APIs in its class path, and open the project properties.
Then pick Java Build Path.
Pick the "Libraries" tab and select one of the UIMA library entries (if you don't have, for instance, uima-core.jar in this list, it's unlikely your code will compile). Each library entry has a small ">" sign on its left - click that to expand the view to see the Javadoc location.
If you highlight that and press edit - you can add a reference to the Javadocs, in the following dialog: 


image::images/references/ref.javadocs/image002.jpg[Screenshot of attaching Javadoc to source in Eclipse]

Once you do this, Eclipse can show you Javadocs for UIMA APIs as you work.
To see the Javadoc for a UIMA API, you can hover over the API class or method, or select it and press shift-F2, or use the menu Navigate →Open External Javadoc, or open the Javadoc view (__Window → Show View → Other → Java → Javadoc__).

In a similar manner, you can attach the source for the UIMA framework, if you download the source distribution.
The source corresponding to particular releases is available from the Apache UIMA web site (http://uima.apache.org) on the downloads page.

[[ugr.ref.javadocs.libraries]]
== Using named Eclipse User Libraries

You can also create a named "user library" in Eclipse containing the UIMA Jars, and attach the Javadocs (or optionally, the sources); this named library is saved in the Eclipse workspace.
Once created, it can be added to the classpath of newly created Eclipse projects.

Use the menu option __Project → Properties → Java Build Path__, and then pick the __Libraries_- tab, and click the __Add Library__ button.
Then select __User Libraries__, click __Next__, and pick the library you created for the UIMA Jars.

To create this library in the workspace, use the same menu picks as above, but after you select the User Libraries and click "Next", you can click the "New Library..." button to define your new library.
You use the "Add Jars" button and multi-select all the Jars in the lib directory of the UIMA binary distribution.
Then you add the Javadoc attachment for each Jar.
The path to use is `file:/` -- insert the path to your install of UIMA -- `/docs/api`.
After you do this for the first Jar, you can copy this string to the clipboard and paste it into the rest of the Jars.