Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKai Maetzel2004-06-21 16:45:50 +0000
committerKai Maetzel2004-06-21 16:45:50 +0000
commit2af6444fe6dd5dfdeebd097a41e32f25b97d5e8d (patch)
treed8d495279ff44237b2a87bc35548f9031b6058ed
parent500246df7e56aa088e4269881a8b62f4c281e2da (diff)
downloadeclipse.platform.text-2af6444fe6dd5dfdeebd097a41e32f25b97d5e8d.tar.gz
eclipse.platform.text-2af6444fe6dd5dfdeebd097a41e32f25b97d5e8d.tar.xz
eclipse.platform.text-2af6444fe6dd5dfdeebd097a41e32f25b97d5e8d.zip
updated Javadoc
-rw-r--r--org.eclipse.text/src/org/eclipse/jface/text/DocumentEvent.java18
-rw-r--r--org.eclipse.text/src/org/eclipse/jface/text/DocumentPartitioningChangedEvent.java16
-rw-r--r--org.eclipse.text/src/org/eclipse/jface/text/IRepairableDocument.java15
-rw-r--r--org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java21
-rw-r--r--org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManagerExtension.java11
-rw-r--r--org.eclipse.text/src/org/eclipse/jface/text/ISynchronizable.java37
6 files changed, 70 insertions, 48 deletions
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/DocumentEvent.java b/org.eclipse.text/src/org/eclipse/jface/text/DocumentEvent.java
index f63ed6639..d47b29e12 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/DocumentEvent.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/DocumentEvent.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
@@ -13,12 +13,12 @@ package org.eclipse.jface.text;
/**
- * Specification of changes applied to documents.
- * All changes are represented as replace commands, i.e.
- * specifying a document range whose text gets replaced with different text.
- * In addition to this information, the event also contains the changed document.
- *
- * @see IDocument
+ * Specification of changes applied to documents. All changes are represented as
+ * replace commands, i.e. specifying a document range whose text gets replaced
+ * with different text. In addition to this information, the event also contains
+ * the changed document.
+ *
+ * @see org.eclipse.jface.text.IDocument
*/
public class DocumentEvent {
@@ -52,7 +52,7 @@ public class DocumentEvent {
}
/**
- * Creates a new uninitialized document event.
+ * Creates a new, not initialized document event.
*/
public DocumentEvent() {
}
@@ -67,7 +67,7 @@ public class DocumentEvent {
}
/**
- * Returns the offset of the change
+ * Returns the offset of the change.
*
* @return the offset of the change
*/
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/DocumentPartitioningChangedEvent.java b/org.eclipse.text/src/org/eclipse/jface/text/DocumentPartitioningChangedEvent.java
index 3b852c655..cd299eebf 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/DocumentPartitioningChangedEvent.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/DocumentPartitioningChangedEvent.java
@@ -1,5 +1,5 @@
/**********************************************************************
-Copyright (c) 2000, 2003 IBM Corp. and others.
+Copyright (c) 2000, 2004 IBM Corporation and others.
All rights reserved. This program and the accompanying materials
are made available under the terms of the Common Public License v1.0
which accompanies this distribution, and is available at
@@ -30,6 +30,7 @@ public class DocumentPartitioningChangedEvent {
/**
* Creates a new document partitioning changed event for the given document.
+ * Initially this event is empty, i.e. does not describe any change.
*
* @param document the changed document
*/
@@ -51,13 +52,12 @@ public class DocumentPartitioningChangedEvent {
* if the given partitioning did not change.
*
* @param partitioning the partitioning
- * @return the changed regionn of the given partitioning or <code>null</code>
+ * @return the changed region of the given partitioning or <code>null</code>
*/
public IRegion getChangedRegion(String partitioning) {
return (IRegion) fMap.get(partitioning);
}
-
/**
* Returns the set of changed partitionings.
*
@@ -82,18 +82,18 @@ public class DocumentPartitioningChangedEvent {
}
/**
- * Returns <code>true</code> if the set of changed partitionings is empty. <code>false</code>
- * otherwise.
+ * Returns <code>true</code> if the set of changed partitionings is empty,
+ * <code>false</code> otherwise.
*
- * @return <code>true</code> if the set of changed partitionings is empty.
+ * @return <code>true</code> if the set of changed partitionings is empty
*/
public boolean isEmpty() {
return fMap.isEmpty();
}
/**
- * Returns the coverage of this event. This is the minimal region that contains all
- * changed regions of all changed partitionings.
+ * Returns the coverage of this event. This is the minimal region that
+ * contains all changed regions of all changed partitionings.
*
* @return the coverage of this event
*/
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/IRepairableDocument.java b/org.eclipse.text/src/org/eclipse/jface/text/IRepairableDocument.java
index 1e824bce0..8277a2a69 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/IRepairableDocument.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/IRepairableDocument.java
@@ -1,5 +1,5 @@
/**********************************************************************
-Copyright (c) 2000, 2003 IBM Corp. and others.
+Copyright (c) 2000, 2004 IBM Corporation and others.
All rights reserved. This program and the accompanying materials
are made available under the terms of the Common Public License v1.0
which accompanies this distribution, and is available at
@@ -11,20 +11,17 @@ Contributors:
package org.eclipse.jface.text;
/**
- * Interface implemented by <code>IDocument</code> implementers that offer
- * repair methods on their documents. The following repair methods are
- * provided:
- * <ul>
- * <li>repairing line information</li>
- * </ul>
+ * Tagging interface to be implemented by
+ * {@link org.eclipse.jface.text.IDocument}implementers that offer a line
+ * repair method on the documents.
*
+ * @see org.eclipse.jface.text.IDocument
* @since 3.0
*/
public interface IRepairableDocument {
/**
- * Repairs the line information of this document.
+ * Repairs the line information of the document implementing this interface.
*/
void repairLineInformation();
-
}
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java b/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java
index 98e9d4828..6349aaa1b 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
@@ -15,13 +15,23 @@ package org.eclipse.jface.text;
* Slave documents are documents whose contents is defined in terms of a master
* document. Thus, slave documents usually reflect a projection of the master document.
* Slave documents are causally connected to the master document. This means, changes
- * of the master document have immediate effect in the slave document and vice versa.<p>
+ * of the master document have immediate effect on the slave document and vice versa.<p>
*
- * A slave document manager creates slave documents for given master documents. manages the
- * life cycle of the slave documents and keeps track of the information flow between
+ * A slave document manager creates slave documents for given master documents, manages the
+ * life cycle of the slave documents, and keeps track of the information flow between
* master and slave documents. The slave document manager defines the construction rules of the
* slave documents in terms of the master document.<p>
*
+* In order to provided backward compatibility for clients of <code>ISlaveDocumentManager</code>, extension
+ * interfaces are used to provide a means of evolution. The following extension interfaces
+ * exist:
+ * <ul>
+ * <li> {@link org.eclipse.jface.text.ISlaveDocumentManagerExtension} since version 3.0 extending the protocol
+ * with an access to all managed slave document for a given master document. </li>
+ * </ul>
+ *
+ *
+ * @see org.eclipse.jface.text.IDocument
* @since 2.1
*/
public interface ISlaveDocumentManager {
@@ -34,7 +44,7 @@ public interface ISlaveDocumentManager {
*
* @param master the master document
* @return the newly created slave document
- * @see ISlaveDocumentManager#freeSlaveDocument(IDocument)
+ * @see #freeSlaveDocument(IDocument)
*/
IDocument createSlaveDocument(IDocument master);
@@ -45,6 +55,7 @@ public interface ISlaveDocumentManager {
* this manager using <code>createSlaveDocument</code>.
*
* @param slave the slave document to be freed
+ * @see #createSlaveDocument(IDocument)
*/
void freeSlaveDocument(IDocument slave);
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManagerExtension.java b/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManagerExtension.java
index d4868f956..af1485af3 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManagerExtension.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManagerExtension.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
@@ -11,15 +11,18 @@
package org.eclipse.jface.text;
/**
- * Extension interface for <code>ISlaveDocumentManager</code>. Adds access to
- * the list of all slave documents for a given master document.
+ * Extension interface for {@link org.eclipse.jface.text.ISlaveDocumentManager}.
+ * <p>
+ * Adds access to the list of all slave documents for a given master document.
*
+ * @see org.eclipse.jface.text.ISlaveDocumentManager
* @since 3.0
*/
public interface ISlaveDocumentManagerExtension {
/**
- * Returns the list of slave documents for the given master document.
+ * Returns the list of slave documents for the given master document or
+ * <code>null</code> if there are no such slave document.
*
* @param master the master document
* @return the list of slave documents or <code>null</code>
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ISynchronizable.java b/org.eclipse.text/src/org/eclipse/jface/text/ISynchronizable.java
index f604aee66..1aed67fb9 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ISynchronizable.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ISynchronizable.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
@@ -11,26 +11,37 @@
package org.eclipse.jface.text;
/**
- * Interface for objects which can be set into a synchronized mode when needed.
- * For that, the lock object must be set.
+ * Interface for text related objects which may be used in the multi-threaded
+ * context and thus must provide a way to prevent concurrent access and
+ * manipulation.
+ * <p>
+ * In order to reduce the probability of dead locks clients should synchronize
+ * their access to these objects by using the provided lock object rather than
+ * the object itself.
+ * <p>
+ * Managing objects can use the <code>setLockObject</code> method in order to
+ * synchronize whole sets of objects.
*
* @since 3.0
*/
public interface ISynchronizable {
/**
- * Sets the lock object for this object. If the lock object is not <code>null</code>
- * subsequent calls to methods of this object are synchronized on this lock
- * object.
- *
- * @param lockObject the lock object. May be <code>null</code>.
- */
+ * Sets the lock object for this object. If the lock object is not
+ * <code>null</code> subsequent calls to specified methods of this object
+ * are synchronized on this lock object. Which methods are synchronized is
+ * specified by the implementer.
+ *
+ * @param lockObject the lock object. May be <code>null</code>.
+ */
void setLockObject(Object lockObject);
/**
- * Returns the lock object or <code>null</code> if there is none.
- *
- * @return the lock object or <code>null</code>
- */
+ * Returns the lock object or <code>null</code> if there is none. Clients
+ * should use the lock object in order to synchronize concurrent access to
+ * the implementer.
+ *
+ * @return the lock object or <code>null</code>
+ */
Object getLockObject();
} \ No newline at end of file

Back to the top