mirrors/cdt
1
0
Fork 0
mirror of https://github.com/eclipse-cdt/cdt synced 2025-06-09 10:46:02 +02:00
Code Issues Wiki Activity

[cleanup] Add @noimplement and similar API Tools Javadoc Markup

Browse source
This commit is contained in:
Martin Oberhuber 2008-03-28 14:27:50 +00:00
parent 7eebb4ff9f
commit 0f05234334
4 changed files with 130 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
org.eclipse.tm.terminal.view/src/org/eclipse/tm/internal/terminal/view/PageBook.java
View file

@ -15,12 +15,10 @@ import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control; import org.eclipse.swt.widgets.Control;
/** /**
* A pagebook is a composite control where only a single control is visible * A pagebook is a composite control where only a single control is visible at a
* at a time. It is similar to a notebook, but without tabs. * time. It is similar to a notebook, but without tabs.
* <p> *
* This class may be instantiated; it is not intended to be subclassed. * @noextend This class is not intended to be subclassed by clients.
* </p>
*
*/ */
public class PageBook extends Composite { public class PageBook extends Composite {
private StackLayout fLayout; private StackLayout fLayout;

31
org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java
View file

@ -1,11 +1,11 @@
/******************************************************************************* /*******************************************************************************
* Copyright (c) 2006, 2007 Wind River Systems, Inc. and others. * Copyright (c) 2006, 2007 Wind River Systems, Inc. and others.
* All rights reserved. This program and the accompanying materials * All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0 * are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at * which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html * http://www.eclipse.org/legal/epl-v10.html
* *
* Contributors: * Contributors:
* Michael Scharf (Wind River) - initial API and implementation * Michael Scharf (Wind River) - initial API and implementation
* Martin Oberhuber (Wind River) - fixed copyright headers and beautified * Martin Oberhuber (Wind River) - fixed copyright headers and beautified
*******************************************************************************/ *******************************************************************************/
@ -17,18 +17,19 @@ import org.eclipse.swt.widgets.Shell;
/** /**
* Represents the terminal view as seen by a terminal connection. * Represents the terminal view as seen by a terminal connection.
*
* <p> Not to be implemented by clients.
* @author Michael Scharf
* <p> * <p>
* <strong>EXPERIMENTAL</strong>. This class or interface has been added as * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
* part of a work in progress. There is no guarantee that this API will * part of a work in progress. There is no guarantee that this API will work or
* work or that it will remain the same. Please do not use this API without * that it will remain the same. Please do not use this API without consulting
* consulting with the <a href="http://www.eclipse.org/dsdp/tm/">Target Management</a> team. * with the <a href="http://www.eclipse.org/dsdp/tm/">Target Management</a>
* team.
* </p> * </p>
*
* @author Michael Scharf
* @noimplement This interface is not intended to be implemented by clients.
*/ */
public interface ITerminalControl { public interface ITerminalControl {
/** /**
* @return the current state of the connection * @return the current state of the connection
*/ */
@ -38,7 +39,7 @@ public interface ITerminalControl {
* @param state * @param state
*/ */
void setState(TerminalState state); void setState(TerminalState state);
/** /**
* A shell to show dialogs. * A shell to show dialogs.
* @return the shell in which the terminal is shown. * @return the shell in which the terminal is shown.
@ -48,7 +49,7 @@ public interface ITerminalControl {
/** /**
* Show a text in the terminal. If puts newlines at the beginning and the end. * Show a text in the terminal. If puts newlines at the beginning and the end.
* @param text * @param text
* TODO: Michael Scharf: Is this really needed? * TODO: Michael Scharf: Is this really needed?
*/ */
void displayTextInTerminal(String text); void displayTextInTerminal(String text);
@ -71,5 +72,5 @@ public interface ITerminalControl {
* TODO: Michael Scharf: Should be replaced by a better error notification mechanism! * TODO: Michael Scharf: Should be replaced by a better error notification mechanism!
*/ */
void setMsg(String msg); void setMsg(String msg);
} }

65
org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java
View file

@ -1,23 +1,24 @@
/******************************************************************************* /*******************************************************************************
* Copyright (c) 2007 Wind River Systems, Inc. and others. * Copyright (c) 2007 Wind River Systems, Inc. and others.
* All rights reserved. This program and the accompanying materials * All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0 * are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at * which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html * http://www.eclipse.org/legal/epl-v10.html
* *
* Contributors: * Contributors:
* Michael Scharf (Wind River) - initial API and implementation * Michael Scharf (Wind River) - initial API and implementation
*******************************************************************************/ *******************************************************************************/
package org.eclipse.tm.terminal.model; package org.eclipse.tm.terminal.model;
/** /**
* A writable matrix of characters and {@link Style}. This is intended to be the * A writable matrix of characters and {@link Style}. This is intended to be
* low level representation of the text of a Terminal. Higher layers are responsible * the low level representation of the text of a Terminal. Higher layers are
* to fill the text and styles into this representation. * responsible to fill the text and styles into this representation.
* * <p>
* <p><b>Note: </b> Implementations of this interface has to be thread safe. * <b>Note: </b> Implementations of this interface has to be thread safe.
* <p><b>Note: </b> This interface is not intended to be implemented by clients. * </p>
* @noimplement This interface is not intended to be implemented by clients.
*/ */
public interface ITerminalTextData extends ITerminalTextDataReadOnly { public interface ITerminalTextData extends ITerminalTextDataReadOnly {
@ -61,30 +62,30 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
* @param style the style or null * @param style the style or null
*/ */
void setChars(int line, int column, char[] chars, int start, int len, Style style); void setChars(int line, int column, char[] chars, int start, int len, Style style);
/** /**
* Cleans the entire line. * Cleans the entire line.
* @param line * @param line
*/ */
void cleanLine(int line); void cleanLine(int line);
// /** // /**
// * @param line // * @param line
// * @return true if this line belongs to the previous line but is simply // * @return true if this line belongs to the previous line but is simply
// * wrapped. // * wrapped.
// */ // */
// boolean isWrappedLine(int line); // boolean isWrappedLine(int line);
// //
// /** // /**
// * Makes this line an extension to the previous line. Wrapped lines get folded back // * Makes this line an extension to the previous line. Wrapped lines get folded back
// * when the width of the terminal changes // * when the width of the terminal changes
// * @param line // * @param line
// * @param extendsPreviousLine // * @param extendsPreviousLine
// */ // */
// void setWrappedLine(int line, boolean extendsPreviousLine); // void setWrappedLine(int line, boolean extendsPreviousLine);
/** /**
* Shifts some lines up or down. The "empty" space is filled with <code>'\000'</code> chars * Shifts some lines up or down. The "empty" space is filled with <code>'\000'</code> chars
* and <code>null</code> {@link Style} * and <code>null</code> {@link Style}
* <p>To illustrate shift, here is some sample data: * <p>To illustrate shift, here is some sample data:
* <pre> * <pre>
@ -100,7 +101,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
* 0 aaaa * 0 aaaa
* 1 cccc * 1 cccc
* 2 dddd * 2 dddd
* 3 * 3
* 4 eeee * 4 eeee
* </pre> * </pre>
* *
@ -108,7 +109,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
* Shift a region of 3 lines <b>down</b> by one line <code>shift(1,3,1)</code> * Shift a region of 3 lines <b>down</b> by one line <code>shift(1,3,1)</code>
* <pre> * <pre>
* 0 aaaa * 0 aaaa
* 1 * 1
* 2 bbbb * 2 bbbb
* 3 cccc * 3 cccc
* 4 eeee * 4 eeee
@ -119,7 +120,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
* Negative number means scroll down, positive scroll up (see example above). * Negative number means scroll down, positive scroll up (see example above).
*/ */
void scroll(int startLine, int size, int shift); void scroll(int startLine, int size, int shift);
/**Adds a new line to the terminal. If maxHeigth is reached, the entire terminal /**Adds a new line to the terminal. If maxHeigth is reached, the entire terminal
* will be scrolled. Else a line will be added. * will be scrolled. Else a line will be added.
*/ */
@ -145,7 +146,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
* @param length * @param length
*/ */
void copyRange(ITerminalTextData source, int sourceStartLine, int destStartLine,int length); void copyRange(ITerminalTextData source, int sourceStartLine, int destStartLine,int length);
void setCursorLine(int line); void setCursorLine(int line);
void setCursorColumn(int column); void setCursorColumn(int column);
} }

143
org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
View file

@ -1,11 +1,11 @@
/******************************************************************************* /*******************************************************************************
* Copyright (c) 2007 Wind River Systems, Inc. and others. * Copyright (c) 2007 Wind River Systems, Inc. and others.
* All rights reserved. This program and the accompanying materials * All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0 * are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at * which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html * http://www.eclipse.org/legal/epl-v10.html
* *
* Contributors: * Contributors:
* Michael Scharf (Wind River) - initial API and implementation * Michael Scharf (Wind River) - initial API and implementation
*******************************************************************************/ *******************************************************************************/
package org.eclipse.tm.terminal.model; package org.eclipse.tm.terminal.model;
@ -13,62 +13,73 @@ package org.eclipse.tm.terminal.model;
/** /**
* This class maintains a snapshot of an instance of {@link ITerminalTextData}. * This class maintains a snapshot of an instance of {@link ITerminalTextData}.
* While the {@link ITerminalTextData} continues changing, the snapshot remains * While the {@link ITerminalTextData} continues changing, the snapshot remains
* unchanged until the next snapshot is taken by calling {@link #updateSnapshot(boolean)}. * unchanged until the next snapshot is taken by calling
* This is important, because the {@link ITerminalTextData} might get * {@link #updateSnapshot(boolean)}. This is important, because the
* modified by another thread. Suppose you would want to draw the content of * {@link ITerminalTextData} might get modified by another thread. Suppose you
* the {@link ITerminalTextData} using the following loop: * would want to draw the content of the {@link ITerminalTextData} using the
* following loop:
*
* <pre> * <pre>
* for(int line=0;line&lt;term.getHeight();line++) * for (int line = 0; line &lt; term.getHeight(); line++)
* for(int column=0; column&lt;term.getWidth();column++) * for (int column = 0; column &lt; term.getWidth(); column++)
* drawCharacter(column,line,term.getChar(column,line),term.getStyle(column,line)); * drawCharacter(column, line, term.getChar(column, line), term.getStyle(column, line));
* </pre> * </pre>
* 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 * This might fail because the background thread could change the dimensions of
* put a <code>synchronized(term){}</code> statement around the code. This has * the {@link ITerminalTextData} while you iterate the loop. One solution would
* two problems: 1. you would have to know about the internals of the synchronisation * be to put a <code>synchronized(term){}</code> statement around the code.
* of {@link ITerminalTextData}. 2. The other thread that changes {@link ITerminalTextData} * This has two problems: 1. you would have to know about the internals of the
* is blocked while the potentially slow drawing is done. * synchronisation of {@link ITerminalTextData}. 2. The other thread that
* changes {@link ITerminalTextData} is blocked while the potentially slow
* drawing is done.
* <p> * <p>
* <b>Solution:</b> Take a snapshot of the terminal and use the snapshot to draw * <b>Solution:</b> Take a snapshot of the terminal and use the snapshot to
* the content. There is no danger that the data structure get changed while * draw the content. There is no danger that the data structure get changed
* you draw. There are also methods to find out what has changed to minimize * while you draw. There are also methods to find out what has changed to
* the number of lines that get redrawn.</p> * minimize the number of lines that get redrawn.
*
* <p><b>Drawing optimization</b>: To optimize redrawing of changed lines, this class keeps
* track of lines that have changed since the previous snapshot.</p>
*
* <pre>
* // iterate over the potentially changed lines
* for(int line=snap.getFirstChangedLine();line&lt;=snap.getLastChangedLine();line++)
* // redraw only if the line has changed
* if(snap.hasLineChanged(line))
* for(int column=0; column&lt;snap.getWidth();column++)
* drawCharacter(column,line,snap.getChar(column,line),snap.getStyle(column,line));
* </pre>
*
* <p><b>Scroll optimization:</b> 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 <code>true</code> for
* the <code>detectScrolling</code> parameter. The object will keep track of scrolling.
* The UI must <b>first</b> handle the scrolling and then use the {@link #hasLineChanged(int)}
* method to determine scrolling:
* <pre>
* // scroll the visible region of the UI <b>before</b> drawing the changed lines.
* doUIScrolling(snap.getScrollChangeY(),snap.getScrollChangeN(),snap.getScrollChangeShift());
* // iterate over the potentially changed lines
* for(int line=snap.getFirstChangedLine();line&lt;=snap.getFirstChangedLine();line++)
* // redraw only if the line has changed
* if(snap.hasLineChanged(line))
* for(int column=0; column&lt;snap.getWidth();column++)
* drawCharacter(column,line,snap.getChar(column,line),snap.getStyle(column,line));
* </pre>
* </p> * </p>
* *
* <p><b>Note</b>: This interface is not intended to be implemented by clients.</p> * <p>
* <p><b>Threading Note</b>: This class is not thread save! All methods have to be called by * <b>Drawing optimization</b>: To optimize redrawing of changed lines, this
* the a same thread, that created the instance by calling * class keeps track of lines that have changed since the previous snapshot.
* {@link ITerminalTextDataReadOnly#makeSnapshot()}. </p> * </p>
*
* <pre>
* // iterate over the potentially changed lines
* for (int line = snap.getFirstChangedLine(); line &lt;= snap.getLastChangedLine(); line++)
* // redraw only if the line has changed
* if (snap.hasLineChanged(line))
* for (int column = 0; column &lt; snap.getWidth(); column++)
* drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
* </pre>
*
* <p>
* <b>Scroll optimization:</b> 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 <code>true</code> for
* the <code>detectScrolling</code> parameter. The object will keep track of
* scrolling. The UI must <b>first</b> handle the scrolling and then use the
* {@link #hasLineChanged(int)} method to determine scrolling:
*
* <pre>
* // scroll the visible region of the UI &lt;b&gt;before&lt;/b&gt; drawing the changed lines.
* doUIScrolling(snap.getScrollChangeY(), snap.getScrollChangeN(), snap.getScrollChangeShift());
* // iterate over the potentially changed lines
* for (int line = snap.getFirstChangedLine(); line &lt;= snap.getFirstChangedLine(); line++)
* // redraw only if the line has changed
* if (snap.hasLineChanged(line))
* for (int column = 0; column &lt; snap.getWidth(); column++)
* drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
* </pre>
* </p>
* <p>
* <b>Threading Note</b>: 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()}.
* </p>
*
* @noimplement This interface is not intended to be implemented by clients.
*/ */
public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly { public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
/** /**
@ -79,7 +90,7 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
* is called and a new snapshot needs to be updated again. * is called and a new snapshot needs to be updated again.
* <p> * <p>
* A typical terminal view would not update the snapshot immediately * A typical terminal view would not update the snapshot immediately
* after the {@link #snapshotOutOfDate(ITerminalTextDataSnapshot)} has been called. It would introduce a * 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. * delay to update the UI (and the snapshot} 10 or 20 times per second.
* *
* <p>Make sure you don't spend too much time in this method. * <p>Make sure you don't spend too much time in this method.
@ -94,7 +105,7 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
} }
void addListener(SnapshotOutOfDateListener listener); void addListener(SnapshotOutOfDateListener listener);
void removeListener(SnapshotOutOfDateListener listener); void removeListener(SnapshotOutOfDateListener listener);
/** /**
* Ends the listening to the {@link ITerminalTextData}. After this * Ends the listening to the {@link ITerminalTextData}. After this
* has been called no new snapshot data is collected. * has been called no new snapshot data is collected.
@ -115,11 +126,11 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
void setInterestWindow(int startLine, int size); void setInterestWindow(int startLine, int size);
int getInterestWindowStartLine(); int getInterestWindowStartLine();
int getInterestWindowSize(); int getInterestWindowSize();
/** /**
* Create a new snapshot of the {@link ITerminalTextData}. It will efficiently * Create a new snapshot of the {@link ITerminalTextData}. It will efficiently
* copy the data of the {@link ITerminalTextData} into an internal representation. * copy the data of the {@link ITerminalTextData} into an internal representation.
* The snapshot also keeps track of the changes since the previous snapshot. * The snapshot also keeps track of the changes since the previous snapshot.
* <p>With the methods {@link #getFirstChangedLine()}, {@link #getLastChangedLine()} and * <p>With the methods {@link #getFirstChangedLine()}, {@link #getLastChangedLine()} and
* {@link #hasLineChanged(int)} * {@link #hasLineChanged(int)}
* you can find out what has changed in the current snapshot since the previous snapshot. * you can find out what has changed in the current snapshot since the previous snapshot.
@ -134,9 +145,9 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
/** /**
* @return The first line changed in this snapshot compared * @return The first line changed in this snapshot compared
* to the previous snapshot. * to the previous snapshot.
* *
* <p><b>Note:</b> If no line has changed, this * <p><b>Note:</b> If no line has changed, this
* returns {@link Integer#MAX_VALUE} * returns {@link Integer#MAX_VALUE}
* *
* <p><b>Note:</b> if {@link #updateSnapshot(boolean)} has been called with <code>true</code>, * <p><b>Note:</b> if {@link #updateSnapshot(boolean)} has been called with <code>true</code>,
@ -171,11 +182,11 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
* @return true if the line has changed since the previous snapshot * @return true if the line has changed since the previous snapshot
*/ */
boolean hasLineChanged(int line); boolean hasLineChanged(int line);
boolean hasDimensionsChanged(); boolean hasDimensionsChanged();
/** /**
* @return true if the terminal has changed (and not just the * @return true if the terminal has changed (and not just the
* window of interest) * window of interest)
*/ */
boolean hasTerminalChanged(); boolean hasTerminalChanged();
@ -203,7 +214,7 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
* to the previous snapshot. See also {@link ITerminalTextData#scroll(int, int, int)} * to the previous snapshot. See also {@link ITerminalTextData#scroll(int, int, int)}
*/ */
int getScrollWindowShift(); int getScrollWindowShift();
/** /**
* @return The {@link ITerminalTextData} on that this instance is observing. * @return The {@link ITerminalTextData} on that this instance is observing.
*/ */