diff options
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 f63ed663975..d47b29e1265 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 3b852c65574..cd299eebfa4 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 1e824bce0f5..8277a2a69c9 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 98e9d4828ea..6349aaa1b38 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 d4868f956ac..af1485af359 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 f604aee6631..1aed67fb917 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 |