Fix javadoc in org.eclipse.jgit nls and notes package

Change-Id: I1b65fba5b4856f98974dc10f549540d401ef916f
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>

8 files changed, 94 insertions, 71 deletions

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/nls/NLS.java b/org.eclipse.jgit/src/org/eclipse/jgit/nls/NLS.java
index 5e7beed1e5..3c0d839dfb 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/nls/NLS.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/nls/NLS.java
@@ -68,7 +68,10 @@ import org.eclipse.jgit.errors.TranslationStringMissingException;
  * </pre>
  */
 public class NLS {
-	/** The root locale constant. It is defined here because the Locale.ROOT is not defined in Java 5 */
+	/**
+	 * The root locale constant. It is defined here because the Locale.ROOT is
+	 * not defined in Java 5
+	 */
 	public static final Locale ROOT_LOCALE = new Locale("", "", ""); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
 
 	private static final InheritableThreadLocal<NLS> local = new InheritableThreadLocal<NLS>() {
@@ -105,15 +108,18 @@ public class NLS {
 	/**
 	 * Returns an instance of the translation bundle of the required type. All
 	 * public String fields of the bundle instance will get their values
-	 * injected as described in the {@link TranslationBundle}.
+	 * injected as described in the
+	 * {@link org.eclipse.jgit.nls.TranslationBundle}.
 	 *
-	 * @param <T>
-	 *            required bundle type
 	 * @param type
 	 *            required bundle type
 	 * @return an instance of the required bundle type
-	 * @exception TranslationBundleLoadingException see {@link TranslationBundleLoadingException}
-	 * @exception TranslationStringMissingException see {@link TranslationStringMissingException}
+	 * @exception TranslationBundleLoadingException
+	 *                see
+	 *                {@link org.eclipse.jgit.errors.TranslationBundleLoadingException}
+	 * @exception TranslationStringMissingException
+	 *                see
+	 *                {@link org.eclipse.jgit.errors.TranslationStringMissingException}
 	 */
 	public static <T extends TranslationBundle> T getBundleFor(Class<T> type) {
 		return local.get().get(type);
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/nls/TranslationBundle.java b/org.eclipse.jgit/src/org/eclipse/jgit/nls/TranslationBundle.java
index bde69c0eec..cdd7be266f 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/nls/TranslationBundle.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/nls/TranslationBundle.java
@@ -92,21 +92,22 @@ import org.eclipse.jgit.errors.TranslationStringMissingException;
  * </pre>
  *
  * The translated text is automatically injected into the public String fields
- * according to the locale set with {@link NLS#setLocale(Locale)}. However, the
- * {@link NLS#setLocale(Locale)} method defines only prefered locale which will
- * be honored only if it is supported by the provided resource bundle property
- * files. Basically, this class will use
- * {@link ResourceBundle#getBundle(String, Locale)} method to load a resource
- * bundle. See the documentation of this method for a detailed explanation of
- * resource bundle loading strategy. After a bundle is created the
- * {@link #effectiveLocale()} method can be used to determine whether the bundle
- * really corresponds to the requested locale or is a fallback.
+ * according to the locale set with
+ * {@link org.eclipse.jgit.nls.NLS#setLocale(Locale)}. However, the
+ * {@link org.eclipse.jgit.nls.NLS#setLocale(Locale)} method defines only
+ * prefered locale which will be honored only if it is supported by the provided
+ * resource bundle property files. Basically, this class will use
+ * {@link java.util.ResourceBundle#getBundle(String, Locale)} method to load a
+ * resource bundle. See the documentation of this method for a detailed
+ * explanation of resource bundle loading strategy. After a bundle is created
+ * the {@link #effectiveLocale()} method can be used to determine whether the
+ * bundle really corresponds to the requested locale or is a fallback.
  *
  * <p>
  * To load a String from a resource bundle property file this class uses the
- * {@link ResourceBundle#getString(String)}. This method can throw the
- * {@link MissingResourceException} and this class is not making any effort to
- * catch and/or translate this exception.
+ * {@link java.util.ResourceBundle#getString(String)}. This method can throw the
+ * {@link java.util.MissingResourceException} and this class is not making any
+ * effort to catch and/or translate this exception.
  *
  * <p>
  * To define a concrete translation bundle one has to:
@@ -125,15 +126,20 @@ public abstract class TranslationBundle {
 	private ResourceBundle resourceBundle;
 
 	/**
-	 * @return the locale locale used for loading the resource bundle from which
-	 *         the field values were taken
+	 * Get the locale used for loading the resource bundle from which the field
+	 * values were taken.
+	 *
+	 * @return the locale used for loading the resource bundle from which the
+	 *         field values were taken.
 	 */
 	public Locale effectiveLocale() {
 		return effectiveLocale;
 	}
 
 	/**
-	 * @return the resource bundle on which this translation bundle is based
+	 * Get the resource bundle on which this translation bundle is based.
+	 *
+	 * @return the resource bundle on which this translation bundle is based.
 	 */
 	public ResourceBundle resourceBundle() {
 		return resourceBundle;
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/DefaultNoteMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/DefaultNoteMerger.java
index 2e7327ca32..87bd4b55b1 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/DefaultNoteMerger.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/DefaultNoteMerger.java
@@ -53,7 +53,7 @@ import org.eclipse.jgit.lib.ObjectReader;
 import org.eclipse.jgit.util.io.UnionInputStream;
 
 /**
- * Default implementation of the {@link NoteMerger}.
+ * Default implementation of the {@link org.eclipse.jgit.notes.NoteMerger}.
  * <p>
  * If ours and theirs are both non-null, which means they are either both edits
  * or both adds, then this merger will simply join the content of ours and
@@ -67,6 +67,7 @@ import org.eclipse.jgit.util.io.UnionInputStream;
  */
 public class DefaultNoteMerger implements NoteMerger {
 
+	/** {@inheritDoc} */
 	@Override
 	public Note merge(Note base, Note ours, Note theirs, ObjectReader reader,
 			ObjectInserter inserter) throws IOException {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/Note.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/Note.java
index 41e9bbeef8..7cf40ddf95 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/Note.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/Note.java
@@ -46,7 +46,9 @@ package org.eclipse.jgit.notes;
 import org.eclipse.jgit.lib.AnyObjectId;
 import org.eclipse.jgit.lib.ObjectId;
 
-/** In-memory representation of a single note attached to one object. */
+/**
+ * In-memory representation of a single note attached to one object.
+ */
 public class Note extends ObjectId {
 	private ObjectId data;
 
@@ -63,7 +65,11 @@ public class Note extends ObjectId {
 		data = noteData;
 	}
 
-	/** @return the note content */
+	/**
+	 * Get the note content.
+	 *
+	 * @return the note content.
+	 */
 	public ObjectId getData() {
 		return data;
 	}
@@ -72,6 +78,7 @@ public class Note extends ObjectId {
 		data = newData;
 	}
 
+	/** {@inheritDoc} */
 	@SuppressWarnings("nls")
 	@Override
 	public String toString() {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMap.java
index 44c59260e8..cbef61338f 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMap.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMap.java
@@ -63,10 +63,11 @@ import org.eclipse.jgit.revwalk.RevTree;
 /**
  * Index of notes from a note branch.
  *
- * This class is not thread-safe, and relies on an {@link ObjectReader} that it
- * borrows/shares with the caller. The reader can be used during any call, and
- * is not released by this class. The caller should arrange for releasing the
- * shared {@code ObjectReader} at the proper times.
+ * This class is not thread-safe, and relies on an
+ * {@link org.eclipse.jgit.lib.ObjectReader} that it borrows/shares with the
+ * caller. The reader can be used during any call, and is not released by this
+ * class. The caller should arrange for releasing the shared
+ * {@code ObjectReader} at the proper times.
  */
 public class NoteMap implements Iterable<Note> {
 	/**
@@ -81,10 +82,11 @@ public class NoteMap implements Iterable<Note> {
 	}
 
 	/**
-	 * Shorten the note ref name by trimming off the {@link Constants#R_NOTES}
-	 * prefix if it exists.
+	 * Shorten the note ref name by trimming off the
+	 * {@link org.eclipse.jgit.lib.Constants#R_NOTES} prefix if it exists.
 	 *
 	 * @param noteRefName
+	 *            a {@link java.lang.String} object.
 	 * @return a more user friendly note name
 	 */
 	public static String shortenRefName(String noteRefName) {
@@ -103,13 +105,13 @@ public class NoteMap implements Iterable<Note> {
 	 * @param commit
 	 *            the revision of the note branch to read.
 	 * @return the note map read from the commit.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the repository cannot be accessed through the reader.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             a tree object is corrupt and cannot be read.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             a tree object wasn't actually a tree.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             a reference tree object doesn't exist.
 	 */
 	public static NoteMap read(ObjectReader reader, RevCommit commit)
@@ -128,13 +130,13 @@ public class NoteMap implements Iterable<Note> {
 	 * @param tree
 	 *            the note tree to read.
 	 * @return the note map read from the tree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the repository cannot be accessed through the reader.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             a tree object is corrupt and cannot be read.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             a tree object wasn't actually a tree.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             a reference tree object doesn't exist.
 	 */
 	public static NoteMap read(ObjectReader reader, RevTree tree)
@@ -153,13 +155,13 @@ public class NoteMap implements Iterable<Note> {
 	 * @param treeId
 	 *            the note tree to read.
 	 * @return the note map read from the tree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the repository cannot be accessed through the reader.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             a tree object is corrupt and cannot be read.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             a tree object wasn't actually a tree.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             a reference tree object doesn't exist.
 	 */
 	public static NoteMap readTree(ObjectReader reader, ObjectId treeId)
@@ -197,10 +199,7 @@ public class NoteMap implements Iterable<Note> {
 		this.reader = reader;
 	}
 
-	/**
-	 * @return an iterator that iterates over notes of this NoteMap. Non note
-	 *         entries are ignored by this iterator.
-	 */
+	/** {@inheritDoc} */
 	@Override
 	public Iterator<Note> iterator() {
 		try {
@@ -216,7 +215,7 @@ public class NoteMap implements Iterable<Note> {
 	 * @param id
 	 *            the object to look for.
 	 * @return the note's blob ObjectId, or null if no note exists.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a portion of the note space is not accessible.
 	 */
 	public ObjectId get(AnyObjectId id) throws IOException {
@@ -230,7 +229,7 @@ public class NoteMap implements Iterable<Note> {
 	 * @param id
 	 *            the object to look for.
 	 * @return the note for the given object id, or null if no note exists.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a portion of the note space is not accessible.
 	 */
 	public Note getNote(AnyObjectId id) throws IOException {
@@ -243,7 +242,7 @@ public class NoteMap implements Iterable<Note> {
 	 * @param id
 	 *            the object to look for.
 	 * @return true if a note exists; false if there is no note.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a portion of the note space is not accessible.
 	 */
 	public boolean contains(AnyObjectId id) throws IOException {
@@ -269,11 +268,11 @@ public class NoteMap implements Iterable<Note> {
 	 *            larger than this limit, LargeObjectException will be thrown.
 	 * @return if a note is defined for {@code id}, the note content. If no note
 	 *         is defined, null.
-	 * @throws LargeObjectException
+	 * @throws org.eclipse.jgit.errors.LargeObjectException
 	 *             the note data is larger than {@code sizeLimit}.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             the note's blob does not exist in the repository.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the note's blob cannot be read from the repository
 	 */
 	public byte[] getCachedBytes(AnyObjectId id, int sizeLimit)
@@ -306,7 +305,7 @@ public class NoteMap implements Iterable<Note> {
 	 *            data to associate with the note. This must be the ObjectId of
 	 *            a blob that already exists in the repository. If null the note
 	 *            will be deleted, if present.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a portion of the note space is not accessible.
 	 */
 	public void set(AnyObjectId noteOn, ObjectId noteData) throws IOException {
@@ -337,7 +336,7 @@ public class NoteMap implements Iterable<Note> {
 	 *            inserter to write the encoded {@code noteData} out as a blob.
 	 *            The caller must ensure the inserter is flushed before the
 	 *            updated note map is made available for reading.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the note data could not be stored in the repository.
 	 */
 	public void set(AnyObjectId noteOn, String noteData, ObjectInserter ins)
@@ -361,7 +360,7 @@ public class NoteMap implements Iterable<Note> {
 	 *
 	 * @param noteOn
 	 *            the object to remove the note from.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a portion of the note space is not accessible.
 	 */
 	public void remove(AnyObjectId noteOn) throws IOException {
@@ -376,7 +375,7 @@ public class NoteMap implements Iterable<Note> {
 	 *            Caller is responsible for flushing the inserter before trying
 	 *            to read the objects, or exposing them through a reference.
 	 * @return the top level tree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a tree could not be written.
 	 */
 	public ObjectId writeTree(ObjectInserter inserter) throws IOException {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMapMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMapMerger.java
index 19ec1a13db..ae624797ff 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMapMerger.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMapMerger.java
@@ -62,8 +62,9 @@ import org.eclipse.jgit.treewalk.TreeWalk;
 /**
  * Three-way note tree merge.
  * <p>
- * Direct implementation of NoteMap merger without using {@link TreeWalk} and
- * {@link AbstractTreeIterator}
+ * Direct implementation of NoteMap merger without using
+ * {@link org.eclipse.jgit.treewalk.TreeWalk} and
+ * {@link org.eclipse.jgit.treewalk.AbstractTreeIterator}
  */
 public class NoteMapMerger {
 	private static final FanoutBucket EMPTY_FANOUT = new FanoutBucket(0);
@@ -83,8 +84,9 @@ public class NoteMapMerger {
 	private final MutableObjectId objectIdPrefix;
 
 	/**
-	 * Constructs a NoteMapMerger with custom {@link NoteMerger} and custom
-	 * {@link MergeStrategy}.
+	 * Constructs a NoteMapMerger with custom
+	 * {@link org.eclipse.jgit.notes.NoteMerger} and custom
+	 * {@link org.eclipse.jgit.merge.MergeStrategy}.
 	 *
 	 * @param db
 	 *            Git repository
@@ -104,9 +106,10 @@ public class NoteMapMerger {
 	}
 
 	/**
-	 * Constructs a NoteMapMerger with {@link DefaultNoteMerger} as the merger
-	 * for notes and the {@link MergeStrategy#RESOLVE} as the strategy for
-	 * resolving conflicts on non-notes
+	 * Constructs a NoteMapMerger with
+	 * {@link org.eclipse.jgit.notes.DefaultNoteMerger} as the merger for notes
+	 * and the {@link org.eclipse.jgit.merge.MergeStrategy#RESOLVE} as the
+	 * strategy for resolving conflicts on non-notes
 	 *
 	 * @param db
 	 *            Git repository
@@ -125,7 +128,7 @@ public class NoteMapMerger {
 	 * @param theirs
 	 *            theirs version of the note tree
 	 * @return merge result as a new NoteMap
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 */
 	public NoteMap merge(NoteMap base, NoteMap ours, NoteMap theirs)
 			throws IOException {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMerger.java
index c70211df9e..8df4998a8c 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMerger.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMerger.java
@@ -72,13 +72,13 @@ public interface NoteMerger {
 	 * @param inserter
 	 *            the object inserter that must be used to insert Git objects
 	 * @return the merge result
-	 * @throws NotesMergeConflictException
+	 * @throws org.eclipse.jgit.notes.NotesMergeConflictException
 	 *             in case there was a merge conflict which this note merger
 	 *             couldn't resolve
-	 * @throws IOException
-	 *             in case the reader or the inserter would throw an IOException
-	 *             the implementor will most likely want to propagate it as it
-	 *             can't do much to recover from it
+	 * @throws java.io.IOException
+	 *             in case the reader or the inserter would throw an
+	 *             java.io.IOException the implementor will most likely want to
+	 *             propagate it as it can't do much to recover from it
 	 */
 	Note merge(Note base, Note ours, Note their, ObjectReader reader,
 			ObjectInserter inserter) throws NotesMergeConflictException,
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NotesMergeConflictException.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NotesMergeConflictException.java
index 94fba0fc61..796f1d1d89 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NotesMergeConflictException.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NotesMergeConflictException.java
@@ -49,8 +49,9 @@ import java.text.MessageFormat;
 import org.eclipse.jgit.internal.JGitText;
 
 /**
- * This exception will be thrown from the {@link NoteMerger} when a conflict on
- * Notes content is found during merge.
+ * This exception will be thrown from the
+ * {@link org.eclipse.jgit.notes.NoteMerger} when a conflict on Notes content is
+ * found during merge.
  */
 public class NotesMergeConflictException extends IOException {
 	private static final long serialVersionUID = 1L;