From 463dad2ed6e440a8c90716eed79af50e22dc6be3 Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Mon, 18 Dec 2017 23:29:46 +0100 Subject: [PATCH] Fix javadoc in org.eclipse.jgit nls and notes package Change-Id: I1b65fba5b4856f98974dc10f549540d401ef916f Signed-off-by: Matthias Sohn --- .../src/org/eclipse/jgit/nls/NLS.java | 18 ++++-- .../eclipse/jgit/nls/TranslationBundle.java | 36 ++++++----- .../eclipse/jgit/notes/DefaultNoteMerger.java | 3 +- .../src/org/eclipse/jgit/notes/Note.java | 11 +++- .../src/org/eclipse/jgit/notes/NoteMap.java | 63 +++++++++---------- .../org/eclipse/jgit/notes/NoteMapMerger.java | 19 +++--- .../org/eclipse/jgit/notes/NoteMerger.java | 10 +-- .../notes/NotesMergeConflictException.java | 5 +- 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 5e7beed1e..3c0d839df 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; * */ 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 local = new InheritableThreadLocal() { @@ -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 - * 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 getBundleFor(Class 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 bde69c0ee..cdd7be266 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; * * * 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. * *

* 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. * *

* 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 2e7327ca3..87bd4b55b 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}. *

* 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 41e9bbeef..7cf40ddf9 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 44c59260e..cbef61338 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 { /** @@ -81,10 +82,11 @@ public class NoteMap implements Iterable { } /** - * 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 { * @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 { * @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 { * @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 { 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 iterator() { try { @@ -216,7 +215,7 @@ public class NoteMap implements Iterable { * @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 { * @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 { * @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 { * 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 { * 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 { * 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 { * * @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 { * 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 19ec1a13d..ae624797f 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. *

- * 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 c70211df9..8df4998a8 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 94fba0fc6..796f1d1d8 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;