Bug 558316 - [Javadoc] Fix warnings in platform.teamY20200103-2350Y20191217-0600I20200105-1800I20200105-0955I20200105-0600I20200104-1800I20200104-0625I20200104-0600I20200103-1800I20200102-1800I20200101-1800I20191231-1800I20191230-1800I20191229-2200I20191229-1800I20191228-1800I20191227-1800I20191226-1800I20191225-1800I20191224-1800I20191223-1800I20191222-1800I20191221-2205I20191221-1800I20191220-1805I20191219-1800I20191218-1805I20191218-0015I20191217-1800I20191216-1805I20191215-1800I20191214-1800

Fix syntax warnings aka missing description on @param, etc. Only Javadoc
changes. Should fix all remaining errors and warnings from
platform Javadoc build with -Xdoclint:reference,html,syntax.

Almost exclusively missing @throws descriptions.

Change-Id: Ia17fbb732f77786cc62f817198805e82d4e614d5
Signed-off-by: Paul Pazderski <paul-eclipse@ppazderski.de>

20 files changed, 38 insertions, 37 deletions

diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/PageCompareEditorInput.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/PageCompareEditorInput.java
index 2017ccd88..cb0dd3d9f 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/PageCompareEditorInput.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/PageCompareEditorInput.java
@@ -275,7 +275,7 @@ public abstract class PageCompareEditorInput extends CompareEditorInput implemen
 	 * @param input the input
 	 * @param configuration the compare configuration
 	 * @param monitor a progress monitor
-	 * @throws InvocationTargetException
+	 * @throws InvocationTargetException if an error occurs
 	 */
 	protected abstract void prepareInput(ICompareInput input, CompareConfiguration configuration, IProgressMonitor monitor) throws InvocationTargetException;
 
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/PageSaveablePart.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/PageSaveablePart.java
index 2221dad7e..bd5d1d270 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/PageSaveablePart.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/PageSaveablePart.java
@@ -285,7 +285,7 @@ public abstract class PageSaveablePart extends SaveablePartAdapter implements IC
 	 * @param input the input
 	 * @param configuration the compare configuration
 	 * @param monitor a progress monitor
-	 * @throws InvocationTargetException
+	 * @throws InvocationTargetException if an error occurs
 	 */
 	protected abstract void prepareInput(ICompareInput input, CompareConfiguration configuration, IProgressMonitor monitor) throws InvocationTargetException;
 
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/history/ElementLocalHistoryPageSource.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/history/ElementLocalHistoryPageSource.java
index 8bbb71e63..d911a08b2 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/history/ElementLocalHistoryPageSource.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/history/ElementLocalHistoryPageSource.java
@@ -31,7 +31,7 @@ public abstract class ElementLocalHistoryPageSource extends HistoryPageSource {
 	 * @param file the file containing the element
 	 * @param element the element
 	 * @return the previous edition of the element from the local history or <code>null</code>
-	 * @throws TeamException
+	 * @throws TeamException if an error occurs
 	 */
 	public static ITypedElement getPreviousEdition(IFile file, Object element) throws TeamException {
 		return EditionHistoryPage.getPreviousState(file, element);
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/history/RevisionAnnotationController.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/history/RevisionAnnotationController.java
index aba0d322e..b76de29f6 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/history/RevisionAnnotationController.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/history/RevisionAnnotationController.java
@@ -100,7 +100,7 @@ public abstract class RevisionAnnotationController {
 	 * @param file
 	 *            the file to be edited
 	 * @return the open editor on the file
-	 * @throws PartInitException
+	 * @throws PartInitException swallowed
 	 */
 	public static AbstractDecoratedTextEditor openEditor(IWorkbenchPage page, IFile file) throws PartInitException {
 		if (file == null)
@@ -153,7 +153,7 @@ public abstract class RevisionAnnotationController {
 	 * @param storage
 	 *            the storage that provides access to the contents of the file revision
 	 * @return the open editor on the file revision
-	 * @throws PartInitException
+	 * @throws PartInitException if an error occurs
 	 */
 	public static AbstractDecoratedTextEditor openEditor(IWorkbenchPage page,
 			Object fileRevision, IStorage storage) throws PartInitException {
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ISynchronizationCompareAdapter.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ISynchronizationCompareAdapter.java
index 2cfd69929..55b5abcfe 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ISynchronizationCompareAdapter.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ISynchronizationCompareAdapter.java
@@ -123,7 +123,7 @@ public interface ISynchronizationCompareAdapter {
 	 *            a progress monitor
 	 * @return the synchronization state of the element or -1 if the calculation
 	 *         of the state should be done using the resources of the mapping.
-	 * @throws CoreException
+	 * @throws CoreException on failures; depends on concrete implementation
 	 *
 	 * @since 3.3
 	 */
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ISynchronizationCompareInput.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ISynchronizationCompareInput.java
index a913a43c6..160a41125 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ISynchronizationCompareInput.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ISynchronizationCompareInput.java
@@ -45,7 +45,7 @@ public interface ISynchronizationCompareInput extends ICompareInput {
 	 * the compare configuration.
 	 * @param configuration the compare configuration for the editor that will display the input
 	 * @param monitor a progress monitor
-	 * @throws CoreException
+	 * @throws CoreException if an error occurs
 	 */
 	void prepareInput(CompareConfiguration configuration, IProgressMonitor monitor) throws CoreException;
 
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ITeamContentProviderDescriptor.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ITeamContentProviderDescriptor.java
index 01b26bbe0..25f8fa19a 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ITeamContentProviderDescriptor.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ITeamContentProviderDescriptor.java
@@ -56,7 +56,7 @@ public interface ITeamContentProviderDescriptor {
 	 * the content provider of this extension.
 	 * @return a preference page that can be displayed to configure
 	 * the content provider of this extension
-	 * @throws CoreException
+	 * @throws CoreException if an error occurs
 	 */
 	public IPreferencePage createPreferencePage() throws CoreException;
 
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ITeamStateProvider.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ITeamStateProvider.java
index 9cdcf528c..f2ebcacfc 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ITeamStateProvider.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/ITeamStateProvider.java
@@ -70,7 +70,7 @@ public interface ITeamStateProvider {
 	 * @param element
 	 *            the element being decorated
 	 * @return whether the given element has any decorated state
-	 * @throws CoreException
+	 * @throws CoreException if an error occurs
 	 */
 	public boolean hasDecoratedState(Object element) throws CoreException;
 
@@ -137,7 +137,7 @@ public interface ITeamStateProvider {
 	 * @param monitor
 	 *            a progress monitor
 	 * @return the state for the given element or <code>null</code>
-	 * @throws CoreException
+	 * @throws CoreException if an error occurs
 	 */
 	public ITeamStateDescription getStateDescription(Object element,
 			int stateMask, String[] properties, IProgressMonitor monitor)
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationCompareAdapter.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationCompareAdapter.java
index 1a47ec6ae..51b256d51 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationCompareAdapter.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationCompareAdapter.java
@@ -159,7 +159,7 @@ public abstract class SynchronizationCompareAdapter implements ISynchronizationC
 	 *            a progress monitor
 	 * @return the synchronization state of the element or -1 if the calculation
 	 *         of the state should be done using the resources of the mapping.
-	 * @throws CoreException
+	 * @throws CoreException on failures
 	 *
 	 * @since 3.3
 	 */
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationOperation.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationOperation.java
index 6086f3b90..3d1e6a2f6 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationOperation.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationOperation.java
@@ -170,8 +170,8 @@ public abstract class SynchronizationOperation extends TeamOperation {
 	 * execute method. Clients should call either {@link #run()} or {@link #run(IProgressMonitor)}
 	 * to invoke the operation.
 	 * @param monitor a progress monitor
-	 * @throws InvocationTargetException
-	 * @throws InterruptedException
+	 * @throws InvocationTargetException if an error occurs
+	 * @throws InterruptedException if operation is interrupted
 	 */
 	protected abstract void execute(IProgressMonitor monitor) throws InvocationTargetException, InterruptedException;
 
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationStateTester.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationStateTester.java
index 3b76935e2..4f17db818 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationStateTester.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/mapping/SynchronizationStateTester.java
@@ -151,7 +151,7 @@ public class SynchronizationStateTester {
 	 *            present
 	 * @param monitor a progress monitor
 	 * @return the synchronization state of the given element
-	 * @throws CoreException
+	 * @throws CoreException if an error occurs
 	 */
 	public int getState(Object element, int stateMask, IProgressMonitor monitor) throws CoreException {
 		ITeamStateDescription desc = getTeamStateProvider().getStateDescription(element, stateMask, new String[0], monitor);
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizePage.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizePage.java
index 095e9caf0..e9d0e4db9 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizePage.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ISynchronizePage.java
@@ -32,7 +32,7 @@ public interface ISynchronizePage {
 	 * but before <code>Page#createControl(Composite)</code>
 	 *
 	 * @param site the workbench part for the view containing the page
-	 * @throws PartInitException
+	 * @throws PartInitException if an error occurs
 	 */
 	public void init(ISynchronizePageSite site) throws PartInitException;
 
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelMergeOperation.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelMergeOperation.java
index 2c3d941cf..050d0e866 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelMergeOperation.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelMergeOperation.java
@@ -199,7 +199,7 @@ public abstract class ModelMergeOperation extends ModelOperation {
 	 * method must return an instance of {@link IMergeContext}
 	 * that is fully initialized.
 	 * @param monitor a progress monitor
-	 * @throws CoreException
+	 * @throws CoreException if an error occurs
 	 */
 	protected abstract void initializeContext(IProgressMonitor monitor) throws CoreException;
 
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelOperation.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelOperation.java
index 0888ad168..3df4fdfc2 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelOperation.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelOperation.java
@@ -127,7 +127,7 @@ public abstract class ModelOperation extends TeamOperation {
 	 * {@link ISynchronizationScopeManager} for this operation
 	 * is initialized if it was not previously initialized.
 	 * @param monitor a progress monitor
-	 * @throws InvocationTargetException
+	 * @throws InvocationTargetException if an error occurs
 	 */
 	protected void beginOperation(IProgressMonitor monitor) throws InvocationTargetException {
 		initializeScope(monitor);
@@ -410,8 +410,8 @@ public abstract class ModelOperation extends TeamOperation {
 	 * Execute the operation. This method is invoked after the
 	 * scope has been generated.
 	 * @param monitor a progress monitor
-	 * @throws InvocationTargetException
-	 * @throws InterruptedException
+	 * @throws InvocationTargetException if an error occurs
+	 * @throws InterruptedException if operation is interrupted
 	 */
 	protected abstract void execute(IProgressMonitor monitor) throws InvocationTargetException,
 			InterruptedException;
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelParticipantAction.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelParticipantAction.java
index 70a645c86..211afc667 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelParticipantAction.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelParticipantAction.java
@@ -144,8 +144,8 @@ public abstract class ModelParticipantAction extends BaseSelectionListenerAction
 	 * Check to see if the target saveable differs from the currently
 	 * active saveable. If it does, prompt to save changes in the
 	 * active saveable if it is dirty.
-	 * @throws InterruptedException
-	 * @throws InvocationTargetException
+	 * @throws InterruptedException if operation is interrupted
+	 * @throws InvocationTargetException if an error occurs
 	 */
 	protected void handleTargetSaveableChange() throws InvocationTargetException, InterruptedException {
 		final SaveableComparison targetSaveable = getTargetSaveable();
@@ -171,8 +171,8 @@ public abstract class ModelParticipantAction extends BaseSelectionListenerAction
 	 * @param activeSaveable the current saveable
 	 * @param allowCancel whether canceling the action is an option
 	 * @param monitor a progress monitor
-	 * @throws CoreException
-	 * @throws InterruptedException
+	 * @throws CoreException if an error occurs
+	 * @throws InterruptedException if operation is interrupted
 	 */
 	public static void handleTargetSaveableChange(Shell shell, SaveableComparison targetSaveable, SaveableComparison activeSaveable, boolean allowCancel, IProgressMonitor monitor) throws CoreException, InterruptedException {
 		if (activeSaveable != null && targetSaveable != activeSaveable) {
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelSynchronizeParticipant.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelSynchronizeParticipant.java
index d58d58b73..ebb642e29 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelSynchronizeParticipant.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelSynchronizeParticipant.java
@@ -547,7 +547,7 @@ public class ModelSynchronizeParticipant extends
 	 * with a progress monitor, long running operations should be avoided.
 	 * @param manager the restored scope
 	 * @return the context for this participant
-	 * @throws CoreException
+	 * @throws CoreException if restoring context failed
 	 */
 	protected MergeContext restoreContext(ISynchronizationScopeManager manager) throws CoreException {
 		throw new PartInitException(NLS.bind(TeamUIMessages.ModelSynchronizeParticipant_1, getId()));
@@ -619,7 +619,7 @@ public class ModelSynchronizeParticipant extends
 	 * @param cancelAllowed whether the display of the compare input can be canceled
 	 * @param monitor a progress monitor or <code>null</code> if progress reporting is not required
 	 * @return whether the user choose to continue with the display of the given compare input
-	 * @throws CoreException
+	 * @throws CoreException if an error occurs
 	 */
 	public boolean checkForBufferChange(Shell shell, ISynchronizationCompareInput input, boolean cancelAllowed, IProgressMonitor monitor) throws CoreException {
 		SaveableComparison currentBuffer = getActiveSaveable();
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SaveableCompareEditorInput.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SaveableCompareEditorInput.java
index 91a6ca488..ae1bf61e6 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SaveableCompareEditorInput.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SaveableCompareEditorInput.java
@@ -310,8 +310,8 @@ public abstract class SaveableCompareEditorInput extends CompareEditorInput impl
 	 *
 	 * @param monitor a progress monitor
 	 * @return the compare input
-	 * @throws InvocationTargetException
-	 * @throws InterruptedException
+	 * @throws InvocationTargetException if an error occurs
+	 * @throws InterruptedException if operation is interrupted
 	 */
 	protected abstract ICompareInput prepareCompareInput(IProgressMonitor monitor)
 		throws InvocationTargetException, InterruptedException;
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberParticipant.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberParticipant.java
index 84e913422..8e898417a 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberParticipant.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberParticipant.java
@@ -169,12 +169,12 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 
 	/**
 	 * Refresh this participants synchronization state and displays the result in a model dialog.
-	 * @param shell
 	 *
+	 * @param shell parent shell for the dialog
 	 * @param resources the resources to be refreshed.
-	 * @param jobName
+	 * @param jobName the job name or <code>null</code>
 	 * @param taskName the task name to be shown to the user
-	 * @param configuration
+	 * @param configuration the configuration
 	 * @param site the site in which to run the refresh
 	 */
 	public final void refreshInDialog(Shell shell, IResource[] resources, String jobName, String taskName, ISynchronizePageConfiguration configuration, IWorkbenchSite site) {
@@ -205,9 +205,10 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 
 	/**
 	 * Refresh a participant. The returned status describes the result of the refresh.
-	 * @param resources
-	 * @param taskName
-	 * @param monitor
+	 *
+	 * @param resources the resources to be refreshed.
+	 * @param taskName the task name to be shown to the user
+	 * @param monitor monitor for job progress
 	 * @return a status
 	 */
 	public final IStatus refreshNow(IResource[] resources, String taskName, IProgressMonitor monitor) {
@@ -412,7 +413,7 @@ public abstract class SubscriberParticipant extends AbstractSynchronizeParticipa
 	 * Returns the long task name to describe the behavior of the
 	 * refresh operation to the user. This is typically shown in the status line when this subscriber is refreshed
 	 * in the background.
-	 * @param resources
+	 * @param resources resources we are working on to get meaningful task name from
 	 * @return the long task name
 	 * @since 3.1
 	 */
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberTeamStateProvider.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberTeamStateProvider.java
index 23e5562d7..93db55a95 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberTeamStateProvider.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SubscriberTeamStateProvider.java
@@ -86,7 +86,7 @@ public class SubscriberTeamStateProvider extends TeamStateProvider implements IS
 	 * @param stateMask the state mask that indicates which state flags are desired
 	 * @param monitor a progress monitor
 	 * @return the synchronization state of the element
-	 * @throws CoreException
+	 * @throws CoreException if operation failed
 	 */
 	protected final int getSynchronizationState(Object element, int stateMask,
 			IProgressMonitor monitor) throws CoreException {
diff --git a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelAction.java b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelAction.java
index 1a7392e8f..f9f55302c 100644
--- a/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelAction.java
+++ b/bundles/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/SynchronizeModelAction.java
@@ -106,8 +106,8 @@ public abstract class SynchronizeModelAction extends BaseSelectionListenerAction
 	 * by calling <code>getSubscriberOperation</code> and then run. Subclasses may
 	 * override.
 	 *
-	 * @throws InvocationTargetException
-	 * @throws InterruptedException
+	 * @throws InvocationTargetException if an error occurs
+	 * @throws InterruptedException if operation is interrupted
 	 * @since 3.1
 	 */
 	protected void runOperation() throws InvocationTargetException, InterruptedException {