Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKai Maetzel2004-06-21 21:14:51 +0000
committerKai Maetzel2004-06-21 21:14:51 +0000
commit2c7037c256646379faeabe556b81a955bc431413 (patch)
tree992df2e8735d0a7842e0d87e9e400a718fd3735c /org.eclipse.core.filebuffers
parentd7d923a12e38970d37f5fca9a314b1195a7ad9d1 (diff)
downloadeclipse.platform.text-2c7037c256646379faeabe556b81a955bc431413.tar.gz
eclipse.platform.text-2c7037c256646379faeabe556b81a955bc431413.tar.xz
eclipse.platform.text-2c7037c256646379faeabe556b81a955bc431413.zip
updated Javadoc
Diffstat (limited to 'org.eclipse.core.filebuffers')
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/FileBuffers.java14
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IAnnotationModelFactory.java7
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentFactory.java10
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentSetupParticipant.java20
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBuffer.java25
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferListener.java6
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferManager.java35
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IPersistableAnnotationModel.java27
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ISynchronizationContext.java10
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBuffer.java10
-rw-r--r--org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBufferManager.java6
11 files changed, 108 insertions, 62 deletions
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/FileBuffers.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/FileBuffers.java
index 33f15ed33..f682d9e06 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/FileBuffers.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/FileBuffers.java
@@ -1,5 +1,5 @@
/**********************************************************************
-Copyright (c) 2000, 2003 IBM Corp. and others.
+Copyright (c) 2000, 2004 IBM Corp. 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
@@ -10,6 +10,7 @@ Contributors:
**********************************************************************/
package org.eclipse.core.filebuffers;
+
import java.io.File;
import org.eclipse.core.internal.filebuffers.FileBuffersPlugin;
@@ -19,9 +20,11 @@ import org.eclipse.core.resources.IWorkspaceRoot;
import org.eclipse.core.resources.ResourcesPlugin;
import org.eclipse.core.runtime.IPath;
+
/**
* Facade for the file buffers plug-in. Provides access to the
- * text file buffer manager.
+ * text file buffer manager and helper methods for location
+ * handling.
*
* @since 3.0
*/
@@ -35,9 +38,10 @@ public final class FileBuffers {
/**
* Returns the text file buffer manager. May return <code>null</code> if
- * the file buffers plug-in may no be activated.
+ * the file buffers plug-in may no be activated. This is, for example, the
+ * case when the method is called on plug-in shutdown.
*
- * @return the text file buffer manager
+ * @return the text file buffer manager or <code>null</code>
*/
public static ITextFileBufferManager getTextFileBufferManager() {
FileBuffersPlugin plugin= FileBuffersPlugin.getDefault();
@@ -92,7 +96,7 @@ public final class FileBuffers {
* absolute path in the local file system.
* </p>
*
- * @param location
+ * @param location the location
* @return the {@link File} in the local file system for the given location
*/
public static File getSystemFileAtLocation(IPath location) {
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IAnnotationModelFactory.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IAnnotationModelFactory.java
index 22866c1c9..bc091855d 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IAnnotationModelFactory.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IAnnotationModelFactory.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
@@ -19,6 +19,10 @@ import org.eclipse.jface.text.source.IAnnotationModel;
/**
* Factory for text file buffer annotation models. Used by the text file buffer
* manager to create the annotation model for a new text file buffer.
+ * <p>
+ * The expected interface for extension provided for the
+ * <code>"org.eclipse.core.filebuffers.annotationModelCreation"</code>
+ * extension point.
*
* @since 3.0
*/
@@ -27,6 +31,7 @@ public interface IAnnotationModelFactory {
/**
* Creates and returns a new annotation model.
*
+ * @param location the normalized location
* @return a new annotation model
*/
IAnnotationModel createAnnotationModel(IPath location);
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentFactory.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentFactory.java
index a4ffb83db..bd27c2819 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentFactory.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentFactory.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
@@ -13,8 +13,12 @@ package org.eclipse.core.filebuffers;
import org.eclipse.jface.text.IDocument;
/**
- * Factory for text file buffer documents. Used by the text file buffer
- * manager to create the document for a new text file buffer.
+ * Factory for text file buffer documents. Used by the text file buffer manager
+ * to create the document for a new text file buffer.
+ * <p>
+ * The expected interface of extensions provided for the
+ * <code>"org.eclipse.core.filebuffers.documentCreation"</code> extension
+ * point.
*
* @since 3.0
*/
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentSetupParticipant.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentSetupParticipant.java
index 3f1709f45..ab0cfb60d 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentSetupParticipant.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IDocumentSetupParticipant.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
@@ -10,14 +10,22 @@ Contributors:
**********************************************************************/
package org.eclipse.core.filebuffers;
+
import org.eclipse.jface.text.IDocument;
+
/**
- * Participates in the setup of a text file buffer document. Participants have
- * to be aware of the existence of other participants. I.e. should always setup
- * a document in a way that does not interfere with others. E.g., when a
- * participant wants to install partitioning on the document, it should use the
- * <code>IDocumentExtension3</code> API and choose a unique partitioning id.
+ * Participates in the setup of a text file buffer document.
+ * <p>
+ * The expected interface for extensions provided for the
+ * <code>"org.eclipse.core.filebuffers.documentSetup"</code> extension point.
+ * <p>
+ * Participants have to be aware of the existence of other participants. I.e.
+ * they should always setup a document in a way that does not interfere with
+ * others. E.g., when a participant wants to install partitioning on the
+ * document, it should use the
+ * {@link org.eclipse.jface.text.IDocumentExtension3}API and choose a unique
+ * partitioning id.
*
* @since 3.0
* @see org.eclipse.jface.text.IDocumentExtension3
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBuffer.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBuffer.java
index 6cbe1dd87..3a0cac6b7 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBuffer.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBuffer.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
@@ -10,19 +10,26 @@ Contributors:
**********************************************************************/
package org.eclipse.core.filebuffers;
+
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
+
/**
- * A file buffer represents a file that can be edited by more than one client. Editing is
- * session oriented. This means that editing is a sequence of modification steps. The
- * start of the sequence and the end of the sequence are explicitly indicated. There are
- * no time constraints connected with the sequence of modification steps. A file buffer
- * reifies editing sessions and allows them to interleave.<p>
- * It is not specified whether simultaneous editing sessions can be owned by different
- * threads.
+ * A file buffer represents a file that can be edited by more than one client.
+ * Editing is session oriented. This means that editing is a sequence of
+ * modification steps. The start of the sequence and the end of the sequence are
+ * explicitly indicated. There are no time constraints connected with the
+ * sequence of modification steps. A file buffer reifies editing sessions and
+ * allows them to interleave.
+ * <p>
+ * It is not specified whether simultaneous editing sessions can be owned by
+ * different threads.
+ * <p>
+ * Clients are not supposed to implement that interface. Instances of this type
+ * are obtained from a {@link org.eclipse.core.filebuffers.IFileBufferManager}.
*
* @since 3.0
*/
@@ -41,7 +48,7 @@ public interface IFileBuffer {
/**
* Returns whether this file buffer is synchronized with the file system. This is when
- * the file buffer's underlying file is in sync with the file system and the file buffer
+ * the file buffer's underlying file is in synchronization with the file system and the file buffer
* has been initialized after the underlying files has been modified the last time.
*
* @return <code>true</code> if the file buffer is synchronized with the file system
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferListener.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferListener.java
index 01a115495..52257d676 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferListener.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferListener.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
@@ -13,7 +13,7 @@ package org.eclipse.core.filebuffers;
import org.eclipse.core.runtime.IPath;
/**
- * Interface for listeners of file buffer changes.
+ * Interface for listeners to file buffer changes.
*
* @since 3.0
*/
@@ -29,7 +29,7 @@ public interface IFileBufferListener {
/**
* Informs the listener about the disposal of the given buffer.
*
- * @param buffer
+ * @param buffer the disposed file buffer
*/
void bufferDisposed(IFileBuffer buffer);
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferManager.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferManager.java
index f0e7cae7f..9def6296f 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferManager.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IFileBufferManager.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
@@ -8,19 +8,20 @@ http://www.eclipse.org/legal/cpl-v10.html
Contributors:
IBM Corporation - Initial implementation
**********************************************************************/
-
package org.eclipse.core.filebuffers;
+
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
+
/**
* A file buffer manager manages file buffers for files while the files are
* connected to the file buffer manager. In order to connect a file to a file
* buffer manager call <code>connect</code>. After that call has
* successfully completed the file buffer can be obtained by <code>getFileBuffer</code>.
- * The file buffer is created on the first connect and destroyed on the last
+ * The file buffer is created on the first connect and diposed on the last
* disconnect. I.e. the file buffer manager keeps track of how often a file is
* connected and returns the same file buffer to each client as long as the
* file is connected.
@@ -88,13 +89,13 @@ public interface IFileBufferManager {
void setSynchronizationContext(ISynchronizationContext context);
/**
- * Requests that the synchronization context is used to synchronize the
- * given location with its file buffer. This call as no effect if there is
- * no file buffer managed for the given location.
+ * The caller requests that the synchronization context is used to
+ * synchronize the given location with its file buffer. This call as no
+ * effect if there is no file buffer managed for the given location.
* <p>
- * The provided location is either a full path of a workspace resource or
- * an absolute path in the local file system. The file buffer manager does
- * not resolve the location of workspace resources in the case of linked
+ * The provided location is either a full path of a workspace resource or an
+ * absolute path in the local file system. The file buffer manager does not
+ * resolve the location of workspace resources in the case of linked
* resources.
* </p>
*
@@ -103,13 +104,13 @@ public interface IFileBufferManager {
void requestSynchronizationContext(IPath location);
/**
- * No longer requests the synchronization context for the filebuffer for
- * the given location. This method has no effect if there is no file buffer
- * managed for this location.
+ * The caller no longer requests the synchronization context for the file
+ * buffer managed for the given location. This method has no effect if there
+ * is no file buffer managed for this location.
* <p>
- * The provided location is either a full path of a workspace resource or
- * an absolute path in the local file system. The file buffer manager does
- * not resolve the location of workspace resources in the case of linked
+ * The provided location is either a full path of a workspace resource or an
+ * absolute path in the local file system. The file buffer manager does not
+ * resolve the location of workspace resources in the case of linked
* resources.
* </p>
*
@@ -119,8 +120,8 @@ public interface IFileBufferManager {
/**
* Adds the given listener to the list of file buffer listeners. After that
- * call the listener is informated about changes related to this file
- * buffer. If the listener is already registered with the file buffer, this
+ * call the listener is informed about changes related to this file
+ * buffer manager. If the listener is already registered with the file buffer, this
* call has no effect.
*
* @param listener the listener to be added
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IPersistableAnnotationModel.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IPersistableAnnotationModel.java
index 11a4a9a5e..82c681d5c 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IPersistableAnnotationModel.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/IPersistableAnnotationModel.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
@@ -18,25 +18,40 @@ import org.eclipse.jface.text.IDocument;
/**
- * Interface implemented by <code>IAnnotationModel</code> implementers that offer
- * persistable state.
+ * Tagging interface for {@link org.eclipse.jface.text.source.IAnnotationModel} implementers that offer
+ * state persistence.
*
* @since 3.0
*/
public interface IPersistableAnnotationModel {
/**
- * @param document
+ * Transforms the current transient state of the annotation model into a
+ * persistent state.
+ *
+ * @param document the document the annotation model is connected to
+ * @throws CoreException in case the transformation fails
*/
void commit(IDocument document) throws CoreException;
/**
- * @param document
+ * Changes the current transient state of the annotation model to match the
+ * last persisted state.
+ *
+ * @param document the document the annotation model is connected to
+ * @throws CoreException in case accessing the persisted state
*/
void revert(IDocument document) throws CoreException;
/**
- * @param document
+ * Forces this annotation model to re-initialize from the persistent state.
+ * The persistent state must not be the same as the last persisted state.
+ * I.e. external modification may have caused changes to the persistent
+ * state since the last <code>commit</code> or <code>revert</code>
+ * operation.
+ *
+ * @param document the document the annotation model is connected to
+ * @throws CoreException in case accessing the persistent state fails
*/
void reinitialize(IDocument document) throws CoreException;
}
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ISynchronizationContext.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ISynchronizationContext.java
index 046e9a93d..78932ce66 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ISynchronizationContext.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ISynchronizationContext.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,9 +11,11 @@ Contributors:
package org.eclipse.core.filebuffers;
/**
- * Executes runnables that describe how to synchronize a file buffer with its underlying file.
- *
- * @since 3.0
+ * Executes <code>Runnables</code> according to a certain synchronization
+ * policy. This could be that all given <code>Runnables</code> are executed in
+ * a specific thread or environment.
+ *
+ * @since 3.0
*/
public interface ISynchronizationContext {
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBuffer.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBuffer.java
index 2bdd4b5bc..b655dbf58 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBuffer.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBuffer.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
@@ -15,10 +15,10 @@ import org.eclipse.jface.text.IDocument;
import org.eclipse.jface.text.source.IAnnotationModel;
/**
- * A text file buffer is a file buffer for text files. The contents of a text file buffe is
- * given in the form of a document. Also, the text file buffer provides methods to
- * manage the character encoding used to read and write the buffer's underlying
- * text file.
+ * A text file buffer is a file buffer for text files. The contents of a text
+ * file buffer is given in the form of a document and an associated annotation
+ * model. Also, the text file buffer provides methods to manage the character
+ * encoding used to read and write the buffer's underlying text file.
*
* @since 3.0
*/
diff --git a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBufferManager.java b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBufferManager.java
index 74dd895c9..b7d278e4e 100644
--- a/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBufferManager.java
+++ b/org.eclipse.core.filebuffers/src/org/eclipse/core/filebuffers/ITextFileBufferManager.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
@@ -8,9 +8,9 @@ http://www.eclipse.org/legal/cpl-v10.html
Contributors:
IBM Corporation - Initial implementation
**********************************************************************/
-
package org.eclipse.core.filebuffers;
+
import org.eclipse.core.runtime.IPath;
import org.eclipse.jface.text.IDocument;
@@ -19,7 +19,7 @@ import org.eclipse.jface.text.source.IAnnotationModel;
/**
* A text file buffer manager manages text file buffers for files whose contents
- * could be considered text.
+ * is considered text.
*
* @since 3.0
*/

Back to the top