From 489e43c53865f43ad98ecf1e7e82e8bfac64ce1a Mon Sep 17 00:00:00 2001 From: Martin Oberhuber Date: Mon, 19 Jan 2009 14:05:25 +0000 Subject: [PATCH] [261486][api][cleanup] Mark @noimplement interfaces as @noextend --- .../provisional/api/ITerminalConnector.java | 23 ++++---- .../provisional/api/ITerminalControl.java | 15 ++--- .../tm/terminal/model/ITerminalTextData.java | 18 +++--- .../model/ITerminalTextDataReadOnly.java | 24 ++++---- .../model/ITerminalTextDataSnapshot.java | 55 ++++++++++--------- 5 files changed, 73 insertions(+), 62 deletions(-) diff --git a/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalConnector.java b/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalConnector.java index c8dcc844d26..978c4b89fee 100644 --- a/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalConnector.java +++ b/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalConnector.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2006, 2008 Wind River Systems, Inc. and others. + * Copyright (c) 2006, 2009 Wind River Systems, Inc. and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at @@ -8,6 +8,7 @@ * Contributors: * Michael Scharf (Wind River) - initial API and implementation * Martin Oberhuber (Wind River) - fixed copyright headers and beautified + * Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend *******************************************************************************/ package org.eclipse.tm.internal.terminal.provisional.api; @@ -17,15 +18,14 @@ import org.eclipse.core.runtime.IAdaptable; import org.eclipse.tm.internal.terminal.control.ITerminalViewControl; import org.eclipse.tm.internal.terminal.provisional.api.provider.TerminalConnectorImpl; - /** * A contributed connection type to manage a single connection. * * Implementations of this class are contributed through the - * org.eclipse.tm.terminal.terminalConnectors extension point. - * This class gives access to the static markup of a terminal connector - * extension as well as providing the lifecycle management for the dynamically - * loaded {@link TerminalConnectorImpl} instance, which performs the actual + * org.eclipse.tm.terminal.terminalConnectors extension point. This + * class gives access to the static markup of a terminal connector extension as + * well as providing the lifecycle management for the dynamically loaded + * {@link TerminalConnectorImpl} instance, which performs the actual * communications. This pattern allows for lazy initialization, bundle * activation and class loading of the actual {@link TerminalConnectorImpl} * instance. @@ -36,13 +36,14 @@ import org.eclipse.tm.internal.terminal.provisional.api.provider.TerminalConnect * active terminal widget. * * @noimplement This interface is not intended to be implemented by clients. + * @noextend This interface is not intended to be extended by clients. * * @author Michael Scharf *

- * EXPERIMENTAL. This class or interface has been - * added as part of a work in progress. There is no guarantee that this - * API will work or that it will remain the same. Please do not use this - * API without consulting with the EXPERIMENTAL. This class or interface has been added + * as part of a work in progress. There is no guarantee that this API + * will work or that it will remain the same. Please do not use this API + * without consulting with the Target Management team. *

*/ @@ -128,7 +129,7 @@ public interface ITerminalConnector extends IAdaptable { * FIXME should not have UI related stuff in ITerminalConnector, since * connectors may be totally programmatic and UI-less. Better make the * connector adapt to an interface that controls the UI aspect. - * + * * @return a new page that can be used in a dialog to setup this connection. * The dialog should persist its settings with the * {@link #load(ISettingsStore)} and {@link #save(ISettingsStore)} diff --git a/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java b/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java index fc78b8f6092..ea9046b7a92 100644 --- a/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java +++ b/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2006, 2008 Wind River Systems, Inc. and others. + * Copyright (c) 2006, 2009 Wind River Systems, Inc. and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at @@ -9,6 +9,7 @@ * Michael Scharf (Wind River) - initial API and implementation * Martin Oberhuber (Wind River) - fixed copyright headers and beautified * Martin Oberhuber (Wind River) - [204796] Terminal should allow setting the encoding to use + * Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend *******************************************************************************/ package org.eclipse.tm.internal.terminal.provisional.api; @@ -20,15 +21,15 @@ import org.eclipse.swt.widgets.Shell; /** * Represents the terminal view as seen by a terminal connection. *

- * EXPERIMENTAL. This class or interface has been added as - * part of a work in progress. There is no guarantee that this API will work or - * that it will remain the same. Please do not use this API without consulting - * with the Target Management - * team. + * EXPERIMENTAL. This class or interface has been added as part + * of a work in progress. There is no guarantee that this API will work or that + * it will remain the same. Please do not use this API without consulting with + * the Target Management team. *

* * @author Michael Scharf * @noimplement This interface is not intended to be implemented by clients. + * @noextend This interface is not intended to be extended by clients. */ public interface ITerminalControl { @@ -79,7 +80,7 @@ public interface ITerminalControl { * setEncoding() call failed and the fallback default encoding should be * queried, such that e.g. a combobox with encodings to choose can be * properly initialized. - * + * * @return the current Encoding of the Terminal. * @since org.eclipse.tm.terminal 2.0 */ diff --git a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java index 3b2c9ad5932..3ca18158aa3 100644 --- a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java +++ b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java @@ -1,24 +1,26 @@ /******************************************************************************* - * Copyright (c) 2007, 2008 Wind River Systems, Inc. and others. + * Copyright (c) 2007, 2009 Wind River Systems, Inc. and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html - * + * * Contributors: * Michael Scharf (Wind River) - initial API and implementation + * Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend *******************************************************************************/ package org.eclipse.tm.terminal.model; - /** - * A writable matrix of characters and {@link Style}. This is intended to be - * the low level representation of the text of a Terminal. Higher layers are + * A writable matrix of characters and {@link Style}. This is intended to be the + * low level representation of the text of a Terminal. Higher layers are * responsible to fill the text and styles into this representation. *

* Note: Implementations of this interface has to be thread safe. *

+ * * @noimplement This interface is not intended to be implemented by clients. + * @noextend This interface is not intended to be extended by clients. */ public interface ITerminalTextData extends ITerminalTextDataReadOnly { @@ -95,7 +97,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly { * 3 dddd * 4 eeee * - * + * * Shift a region of 3 lines up by one line shift(1,3,-1) * 
 	 * 0 aaaa
@@ -104,8 +106,8 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
 	 * 3
 	 * 4 eeee
 	 *
- * - * + * + * * Shift a region of 3 lines down by one line shift(1,3,1) * 
 	 * 0 aaaa
diff --git a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataReadOnly.java b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataReadOnly.java
index 183446c191d..0503b4c1ddc 100644
--- a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataReadOnly.java
+++ b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataReadOnly.java
@@ -1,16 +1,20 @@
 /*******************************************************************************
- * Copyright (c) 2007 Wind River Systems, Inc. and others.
- * All rights reserved. This program and the accompanying materials 
- * are made available under the terms of the Eclipse Public License v1.0 
- * which accompanies this distribution, and is available at 
- * http://www.eclipse.org/legal/epl-v10.html 
- * 
- * Contributors: 
+ * Copyright (c) 2007, 2009 Wind River Systems, Inc. and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
  * Michael Scharf (Wind River) - initial API and implementation
+ * Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend
  *******************************************************************************/
 package org.eclipse.tm.terminal.model;
 
-
+/**
+ * @noimplement This interface is not intended to be implemented by clients.
+ * @noextend This interface is not intended to be extended by clients.
+ */
 public interface ITerminalTextDataReadOnly {
 
 	/**
@@ -50,14 +54,14 @@ public interface ITerminalTextDataReadOnly {
 	 * can be used to track changes. Make sure to call {@link ITerminalTextDataSnapshot#detach()}
 	 * if you don't need the snapshots anymore.
 	 * 
Note: A new snapshot is empty and needs a call to {@link ITerminalTextDataSnapshot#updateSnapshot(boolean)} to
-	 * get its initial values. You might want to setup the snapshot to your needs by calling 
+	 * get its initial values. You might want to setup the snapshot to your needs by calling
 	 * {@link ITerminalTextDataSnapshot#setInterestWindow(int, int)}.
 	 * 

 	 * @return a new instance of {@link ITerminalTextDataSnapshot} that "listens" to changes of
 	 * this.
 	 */
 	public ITerminalTextDataSnapshot makeSnapshot();
-	
+
 	char[] getChars(int line);
 	Style[] getStyles(int line);
 
diff --git a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
index d7da1963f07..198f5edbacb 100644
--- a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
+++ b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
@@ -1,12 +1,13 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2008 Wind River Systems, Inc. and others.
+ * Copyright (c) 2007, 2009 Wind River Systems, Inc. and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
- * 
+ *
  * Contributors:
  * Michael Scharf (Wind River) - initial API and implementation
+ * Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend
  *******************************************************************************/
 package org.eclipse.tm.terminal.model;
 
@@ -18,32 +19,32 @@ package org.eclipse.tm.terminal.model;
  * {@link ITerminalTextData} might get modified by another thread. Suppose you
  * would want to draw the content of the {@link ITerminalTextData} using the
  * following loop:
- * 
+ *
  * 
  * for (int line = 0; line < term.getHeight(); line++)
  * 	for (int column = 0; column < term.getWidth(); column++)
  * 		drawCharacter(column, line, term.getChar(column, line), term.getStyle(column, line));
  * 

- * 
+ *
  * This might fail because the background thread could change the dimensions of
  * the {@link ITerminalTextData} while you iterate the loop. One solution would
- * be to put a synchronized(term){} statement around the code.
- * This has two problems: 1. you would have to know about the internals of the
+ * be to put a synchronized(term){} statement around the code. This
+ * has two problems: 1. you would have to know about the internals of the
  * synchronisation of {@link ITerminalTextData}. 2. The other thread that
  * changes {@link ITerminalTextData} is blocked while the potentially slow
  * drawing is done.
  * 

- * Solution: Take a snapshot of the terminal and use the snapshot to
- * draw the content. There is no danger that the data structure get changed
- * while you draw. There are also methods to find out what has changed to
- * minimize the number of lines that get redrawn.
+ * Solution: Take a snapshot of the terminal and use the snapshot to draw
+ * the content. There is no danger that the data structure get changed while you
+ * draw. There are also methods to find out what has changed to minimize the
+ * number of lines that get redrawn.
  * 

- * 
+ *
  * 

  * Drawing optimization: To optimize redrawing of changed lines, this
  * class keeps track of lines that have changed since the previous snapshot.
  * 

- * 
+ *
  * 
  * // iterate over the potentially changed lines
  * for (int line = snap.getFirstChangedLine(); line <= snap.getLastChangedLine(); line++)
@@ -52,16 +53,16 @@ package org.eclipse.tm.terminal.model;
  * 		for (int column = 0; column < snap.getWidth(); column++)
  * 			drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
  * 

- * 
+ *
  * 

- * Scroll optimization: Often new lines are appended at the bottom of
- * the terminal and the rest of the lines are scrolled up. In this case all
- * lines would be marked as changed. To optimize for this case,
- * {@link #updateSnapshot(boolean)} can be called with true for
- * the detectScrolling parameter. The object will keep track of
+ * Scroll optimization: Often new lines are appended at the bottom of the
+ * terminal and the rest of the lines are scrolled up. In this case all lines
+ * would be marked as changed. To optimize for this case,
+ * {@link #updateSnapshot(boolean)} can be called with true for the
+ * detectScrolling parameter. The object will keep track of
  * scrolling. The UI must first handle the scrolling and then use the
  * {@link #hasLineChanged(int)} method to determine scrolling:
- * 
+ *
  * 
  * // scroll the visible region of the UI <b>before</b> drawing the changed lines.
  * doUIScrolling(snap.getScrollChangeY(), snap.getScrollChangeN(), snap.getScrollChangeShift());
@@ -72,14 +73,16 @@ package org.eclipse.tm.terminal.model;
  * 		for (int column = 0; column < snap.getWidth(); column++)
  * 			drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
  * 

+ *
  * 

  * 

  * Threading Note: This class is not thread safe! All methods have to be
  * called by the a same thread, that created the instance by calling
  * {@link ITerminalTextDataReadOnly#makeSnapshot()}.
  * 

- * 
+ *
  * @noimplement This interface is not intended to be implemented by clients.
+ * @noextend This interface is not intended to be extended by clients.
  */
 public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	/**
@@ -92,7 +95,7 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	 * A typical terminal view would not update the snapshot immediately
 	 * after the {@link #snapshotOutOfDate(ITerminalTextDataSnapshot)} has been called. It would introduce a
 	 * delay to update the UI (and the snapshot} 10 or 20 times per second.
-	 * 
+	 *
 	 * 
Make sure you don't spend too much time in this method.
 	 */
 	interface SnapshotOutOfDateListener {
@@ -146,10 +149,10 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	/**
 	 * @return The first line changed in this snapshot compared
 	 * to the previous snapshot.
-	 * 
+	 *
 	 * 
Note: If no line has changed, this
 	 * returns {@link Integer#MAX_VALUE}
-	 * 
+	 *
 	 * 
Note: if {@link #updateSnapshot(boolean)} has been called with true,
 	 * then this does not include lines that only have been scrolled. This is the
 	 * first line that has changed after the scroll has been applied.
@@ -161,13 +164,13 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	 * to the previous snapshot. If the height has changed since the
 	 * last update of the snapshot, then the returned value is within
 	 * the new dimensions.
-	 * 
+	 *
 	 * 
Note: If no line has changed, this returns -1
-	 * 
+	 *
 	 * 
Note: if {@link #updateSnapshot(boolean)} has been called with true,
 	 * then this does not include lines that only have been scrolled. This is the
 	 * last line that has changed after the scroll has been applied.
-	 * 
+	 *
 	 * 
A typical for loop using this method would look like this (note the <= in the for loop):
 	 * 
 	 * for(int line=snap.{@link #getFirstChangedLine()}; line <= snap.getLastChangedLine(); line++)