Further enhancements in Javadoc for Core API
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/ElementDeltas.java b/org.eclipse.handly/src/org/eclipse/handly/model/ElementDeltas.java
index ab8f507..6e26596 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/ElementDeltas.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/ElementDeltas.java
@@ -95,11 +95,7 @@
* Returns flags which describe in more detail how an element has changed.
* Such flags should be tested using the <code>&</code> operator.
* For example:
- * <pre>
- * if ((flags & F_CONTENT) != 0)
- * {
- * // a content change
- * }</pre>
+ * <pre> if ((flags & F_CONTENT) != 0) // a content change</pre>
* <p>
* Some change flags make sense for most models and are predefined in
* {@link IElementDeltaConstants}, while others are model-specific and are
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/Elements.java b/org.eclipse.handly/src/org/eclipse/handly/model/Elements.java
index c756244..a58147e 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/Elements.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/Elements.java
@@ -1418,7 +1418,7 @@
Boolean.class).withDefault(false);
/**
- * Returns the buffer opened for the source file. Note that buffers may
+ * Returns a buffer opened for the source file. Note that buffers may
* be shared by multiple clients, so the returned buffer may have unsaved
* changes if it has been modified by another client.
* <p>
@@ -1435,7 +1435,7 @@
* </p>
*
* @param sourceFile not <code>null</code>
- * @return the buffer opened for the source file (never <code>null</code>)
+ * @return a buffer opened for the source file (never <code>null</code>)
* @throws CoreException if the source file does not exist or if an
* exception occurs while accessing its corresponding resource
*/
@@ -1445,7 +1445,7 @@
}
/**
- * Returns the buffer opened for the source file. Note that buffers may
+ * Returns a buffer opened for the source file. Note that buffers may
* be shared by multiple clients, so the returned buffer may have unsaved
* changes if it has been modified by another client.
* <p>
@@ -1476,9 +1476,9 @@
* @param monitor a progress monitor, or <code>null</code>
* if progress reporting is not desired. The caller must not rely on
* {@link IProgressMonitor#done()} having been called by the receiver
- * @return the buffer opened for the source file. May return <code>null</code>
- * if <code>CREATE_BUFFER == false</code> and there is no buffer currently
- * opened for the source file
+ * @return a buffer opened for the source file. May return <code>null</code>
+ * if <code>CREATE_BUFFER</code> is <code>false</code> in the given context
+ * and there is no buffer currently opened for the source file
* @throws CoreException if the source file does not exist or if an
* exception occurs while accessing its corresponding resource
* @throws OperationCanceledException if this method is canceled
@@ -1490,8 +1490,8 @@
}
/**
- * Indicates whether a new buffer should be created if none already exists
- * for the source file. Default value: <code>true</code>.
+ * Indicates whether a new buffer should be created if none already exists.
+ * Default value: <code>true</code>.
*
* @see #getBuffer(ISourceFile, IContext, IProgressMonitor)
*/
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/IElementChangeEvent.java b/org.eclipse.handly/src/org/eclipse/handly/model/IElementChangeEvent.java
index 372be68..c6aae4e 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/IElementChangeEvent.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/IElementChangeEvent.java
@@ -36,8 +36,8 @@
/**
* Returns the type of event being reported.
* <p>
- * Some event types are meaningful for most models and predefined
- * in this interface, while others are model-specific and defined by
+ * Some event types make sense for most models and are predefined
+ * in this interface, while others are model-specific and are defined by
* the model implementor. The range for model-specific types starts from
* <code>0x10000</code> and includes the upper 16 bits of <code>int</code>
* value. The lower 16 bits are reserved for predefined generic event types.
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/IElementDeltaExtension.java b/org.eclipse.handly/src/org/eclipse/handly/model/IElementDeltaExtension.java
index 62523f6..2cedec7 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/IElementDeltaExtension.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/IElementDeltaExtension.java
@@ -73,11 +73,7 @@
* Returns flags which describe in more detail how an element has changed.
* Such flags should be tested using the <code>&</code> operator.
* For example:
- * <pre>
- * if ((flags & F_CONTENT) != 0)
- * {
- * // a content change
- * }</pre>
+ * <pre> if ((flags & F_CONTENT) != 0) // a content change</pre>
* <p>
* Some change flags make sense for most models and are predefined in
* {@link IElementDeltaConstants}, while others are model-specific and are
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceFileExtension.java b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceFileExtension.java
index cec4d8d..17cf072 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/ISourceFileExtension.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/ISourceFileExtension.java
@@ -88,7 +88,7 @@
}
/**
- * Returns the buffer opened for this source file. Note that buffers may
+ * Returns a buffer opened for this source file. Note that buffers may
* be shared by multiple clients, so the returned buffer may have unsaved
* changes if it has been modified by another client.
* <p>
@@ -104,7 +104,7 @@
* change over the lifetime of a working copy.
* </p>
*
- * @return the buffer opened for this source file (never <code>null</code>)
+ * @return a buffer opened for this source file (never <code>null</code>)
* @throws CoreException if this source file does not exist or if an
* exception occurs while accessing its corresponding resource
*/
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/adapter/ICorrespondingElementProvider.java b/org.eclipse.handly/src/org/eclipse/handly/model/adapter/ICorrespondingElementProvider.java
index 9c3ac01..96fddc9 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/adapter/ICorrespondingElementProvider.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/adapter/ICorrespondingElementProvider.java
@@ -16,7 +16,7 @@
import org.eclipse.handly.model.IElement;
/**
- * Defines a one-to-one mapping (injection) of elements from a Handly based model
+ * Defines a one-to-one mapping (injection) of elements from a Handly-based model
* to elements in some other model.
* <p>
* For every <code>IElement</code> <code>e</code> such that
@@ -27,6 +27,8 @@
* <p>
* This interface may be implemented by clients.
* </p>
+ *
+ * @see DefaultContentAdapter
*/
public interface ICorrespondingElementProvider
{
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementDeltaImpl.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementDeltaImpl.java
index a96e85b..67766ed 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementDeltaImpl.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementDeltaImpl.java
@@ -65,11 +65,7 @@
* Returns flags which describe in more detail how an element has changed.
* Such flags should be tested using the <code>&</code> operator.
* For example:
- * <pre>
- * if ((flags & F_CONTENT) != 0)
- * {
- * // a content change
- * }</pre>
+ * <pre> if ((flags & F_CONTENT) != 0) // a content change</pre>
* <p>
* Some change flags make sense for most models and are predefined in
* {@link IElementDeltaConstants}, while others are model-specific and are
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementImpl.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementImpl.java
index 75d7881..384cb09 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementImpl.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementImpl.java
@@ -76,12 +76,12 @@
* to the same parent chain as the given element. This is a handle-only
* method.
* <p>
- * This implementation is provided for the most general case where equal
+ * This implementation accounts for the most general case where equal
* elements may belong to different parent chains. For example, in JDT, equal
* JarPackageFragmentRoots may belong to different Java projects. Specific
* models can provide an optimized implementation. For example, it would be
* possible to just return <code>equals(other)</code> if it were known for
- * a model that equal elements cannot belong to different parent chains.
+ * a model that equal elements might not belong to different parent chains.
* </p>
*
* @param other may be <code>null</code>
@@ -110,7 +110,8 @@
/**
* Returns a string representation of this element handle that can be used
- * to recreate the handle via the model's <code>IElementHandleFactory</code>.
+ * to recreate the handle via the model's {@link
+ * org.eclipse.handly.model.IElementHandleFactory IElementHandleFactory}.
* The format of the string is not specified, but the representation is
* stable across workbench sessions. This is a handle-only method.
*
@@ -224,7 +225,7 @@
* specified in the given context; unrecognized options are ignored and
* an empty context is permitted.
* <p>
- * Implementations are advised to support common options defined in
+ * Implementations are encouraged to support common options defined in
* {@link org.eclipse.handly.util.ToStringOptions ToStringOptions} and
* interpret the {@link org.eclipse.handly.util.ToStringOptions#FORMAT_STYLE
* FORMAT_STYLE} as follows:
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementImplExtension.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementImplExtension.java
index c681774..aa9ea28 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementImplExtension.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/IElementImplExtension.java
@@ -38,11 +38,10 @@
}
/**
- * Given a body, returns the immediate children of this element.
+ * Given a body for this element, returns the immediate children.
*
- * @param body the body corresponding to this element
- * (not <code>null</code>)
- * @return the immediate children of this element (never <code>null</code>).
+ * @param body a body for this element (not <code>null</code>)
+ * @return the immediate children (never <code>null</code>).
* Clients <b>must not</b> modify the returned array.
*/
IElement[] getChildrenFromBody_(Object body);
@@ -117,7 +116,7 @@
/**
* Ensures that this element is open, i.e., it exists and is present in the
- * body cache. Performs atomically. Returns the cached body for this element.
+ * body cache. Returns the cached body for this element.
* <p>
* Implementations are encouraged to support the following standard options,
* which may be specified in the given context:
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceConstructImpl.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceConstructImpl.java
index ddd1473..9bd8793 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceConstructImpl.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceConstructImpl.java
@@ -34,6 +34,12 @@
@Override
IElement getParent_();
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation returns <code>Elements.getResource(getParent_())</code>.
+ * </p>
+ */
@Override
default IResource getResource_()
{
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceElementImpl.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceElementImpl.java
index 3547f13..43610b1 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceElementImpl.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceElementImpl.java
@@ -14,6 +14,7 @@
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;
+import org.eclipse.core.runtime.OperationCanceledException;
import org.eclipse.handly.context.IContext;
import org.eclipse.handly.model.ISourceElement;
import org.eclipse.handly.model.ISourceElementInfo;
@@ -56,6 +57,7 @@
* @throws StaleSnapshotException if snapshot inconsistency is detected,
* i.e., this element's current structure and properties are based on
* a different snapshot
+ * @throws OperationCanceledException if this method is canceled
*/
ISourceElement getSourceElementAt_(int position, IContext context,
IProgressMonitor monitor) throws CoreException;
@@ -71,6 +73,7 @@
* (never <code>null</code>)
* @throws CoreException if this element does not exist or if an
* exception occurs while accessing its corresponding resource
+ * @throws OperationCanceledException if this method is canceled
*/
ISourceElementInfo getSourceElementInfo_(IContext context,
IProgressMonitor monitor) throws CoreException;
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceFileImpl.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceFileImpl.java
index 317232e..9dbe4a3 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceFileImpl.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceFileImpl.java
@@ -90,7 +90,7 @@
throws CoreException;
/**
- * Returns the buffer opened for this source file. Note that buffers may
+ * Returns a buffer opened for this source file. Note that buffers may
* be shared by multiple clients, so the returned buffer may have unsaved
* changes if it has been modified by another client.
* <p>
@@ -121,9 +121,9 @@
* @param monitor a progress monitor, or <code>null</code>
* if progress reporting is not desired. The caller must not rely on
* {@link IProgressMonitor#done()} having been called by the receiver
- * @return the buffer opened for this source file. May return <code>null</code>
- * if <code>CREATE_BUFFER == false</code> and there is no buffer currently
- * opened for this source file
+ * @return a buffer opened for this source file. May return <code>null</code>
+ * if <code>CREATE_BUFFER</code> is <code>false</code> in the given context
+ * and there is no buffer currently opened for the source file
* @throws CoreException if this source file does not exist or if an
* exception occurs while accessing its corresponding resource
* @throws OperationCanceledException if this method is canceled
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceFileImplExtension.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceFileImplExtension.java
index 289c56b..af47a6d 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceFileImplExtension.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/ISourceFileImplExtension.java
@@ -83,8 +83,8 @@
* </li>
* <li>
* {@link #WORKING_COPY_CALLBACK} - Specifies the working copy callback.
- * If set, a different callback instance is required for each call of this
- * method: callbacks may not be shared.
+ * If set, the given callback must be a new instance: callbacks may not be
+ * shared or reused between working copies.
* </li>
* <li>
* {@link #WORKING_COPY_CONTEXT} - Specifies the working copy context.
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/WorkingCopyCallback.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/WorkingCopyCallback.java
index dbb3f24..5642cd9 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/WorkingCopyCallback.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/WorkingCopyCallback.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2017 1C-Soft LLC.
+ * Copyright (c) 2017, 2018 1C-Soft LLC.
*
* This program and the accompanying materials are made available under
* the terms of the Eclipse Public License 2.0 which is available at
@@ -26,8 +26,8 @@
/**
* {@inheritDoc}
* <p>
- * This implementation remembers the given working copy info.
- * Clients may extend this method.
+ * Subclasses may override this method, but must make sure
+ * to call the <b>super</b> implementation.
* </p>
*/
@Override
@@ -39,8 +39,8 @@
/**
* {@inheritDoc}
* <p>
- * This implementation nullifies the remembered working copy info.
- * Clients may extend this method.
+ * Subclasses may override this method, but must make sure
+ * to call the <b>super</b> implementation.
* </p>
*/
@Override
@@ -50,9 +50,10 @@
}
/**
- * Returns the working copy info.
+ * Returns the working copy info {@link #onInit(IWorkingCopyInfo) set}
+ * for this callback.
*
- * @return the working copy info, or <code>null</code>
+ * @return the working copy info
*/
protected final IWorkingCopyInfo getWorkingCopyInfo()
{
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/Body.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/Body.java
index 6bba8be..bacf68c 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/Body.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/Body.java
@@ -14,9 +14,11 @@
package org.eclipse.handly.model.impl.support;
import java.lang.reflect.Array;
+import java.util.Arrays;
import org.eclipse.handly.model.Elements;
import org.eclipse.handly.model.IElement;
+import org.eclipse.handly.util.ArrayUtil;
/**
* Holds cached structure and properties for an {@link IElement}.
@@ -57,12 +59,15 @@
* Sets the child elements for this body. Clients <b>must not</b> modify
* the given array afterwards.
*
- * @param children not <code>null</code>
+ * @param children not <code>null</code>, must not contain <code>null</code>
+ * elements
*/
public void setChildren(IElement[] children)
{
if (children == null)
throw new IllegalArgumentException();
+ if (ArrayUtil.contains(children, null))
+ throw new IllegalArgumentException(Arrays.toString(children));
this.children = children;
}
@@ -107,16 +112,16 @@
/**
* Finds whether this body has had a content change.
* <p>
- * Implementations can compare this body and the given old body (excepting
- * {@link #getChildren() children}) and, if there are differences, insert an
- * appropriate change delta (such as <code>F_CONTENT</code>) for the given
- * element into the delta tree being built. Implementations should not take
+ * Implementations can compare this body and the given old body and,
+ * if there are differences (excepting children), insert an appropriate
+ * change delta (such as <code>F_CONTENT</code>) for the given element into
+ * the delta tree being built. Implementations should not take changes in
* children into account.
* </p>
*
- * @param oldBody the old version of the body (never <code>null</code>)
- * @param element the element this body corresponds to (never <code>null</code>)
- * @param builder represents the delta tree being built (never <code>null</code>)
+ * @param oldBody the old version of the body (not <code>null</code>)
+ * @param element the element this body corresponds to (not <code>null</code>)
+ * @param builder represents the delta tree being built (not <code>null</code>)
*/
public void findContentChange(Body oldBody, IElement element,
IElementDeltaBuilder builder)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementCache.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementCache.java
index 902879a..95a31d2 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementCache.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementCache.java
@@ -45,7 +45,7 @@
/**
* Constructs an empty <code>ElementCache</code> with the given maximum size
- * and the default {@link #getLoadFactor() load factor} of one third.
+ * and a default {@link #getLoadFactor() load factor}.
*
* @param maxSize the maximum size of the cache (the bound)
* @throws IllegalArgumentException if <code>maxSize < 1</code>
@@ -72,7 +72,7 @@
* Returns the load factor of this cache. The load factor determines
* how much space is reclaimed when the cache overflows.
*
- * @return the load factor of the cache
+ * @return the load factor of the cache (a value in the interval (0, 1])
*/
public double getLoadFactor()
{
@@ -171,8 +171,9 @@
* for this method to remove other cache entries along with the given entry
* or, if the given entry cannot currently be evicted, retain it in the cache.
* <p>
- * This implementation invokes <code>
- * ((IElementImplExtension)entry.key).close_(of(CLOSE_HINT, CACHE_OVERFLOW))</code>.
+ * This implementation invokes <code>((IElementImplExtension)entry.key).{@link
+ * IElementImplExtension#close_(org.eclipse.handly.context.IContext) close_
+ * }(of(CLOSE_HINT, CACHE_OVERFLOW))</code>.
* </p>
*/
@Override
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementChangeListenerList.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementChangeListenerList.java
index aeef2a6..98af44f 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementChangeListenerList.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementChangeListenerList.java
@@ -38,9 +38,10 @@
* to this list. Has no effect if an identical listener is already registered
* for these event types.
* <p>
- * After completion of this method, the given listener will be registered
- * for exactly the specified event types. If they were previously registered
- * for other event types, they will be de-registered.
+ * After successful completion of this method, the given listener will be
+ * registered for exactly the specified event types. If it was previously
+ * registered for other event types, it will be de-registered for those
+ * event types.
* </p>
*
* @param listener the listener to add (not <code>null</code>)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementChangeRecorder.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementChangeRecorder.java
index c3224dd..1a95ff2 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementChangeRecorder.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementChangeRecorder.java
@@ -180,8 +180,7 @@
/**
* Returns a new instance of default delta builder rooted at the given
- * element. This method is called internally; it is not intended to be
- * invoked by clients.
+ * element.
* <p>
* This implementation returns a new instance of {@link ElementDelta.Builder}.
* The root delta is created via the {@link ElementDelta.Factory} registered
@@ -205,9 +204,9 @@
}
/**
- * Remembers the given body for the given element. This method is called
- * internally; it is not intended to be invoked by clients. Subclasses
- * may extend this method.
+ * Remembers the given body for the given element. Subclasses may override
+ * this method, but must make sure to call the <b>super</b> implementation.
+ * This method is not intended to be invoked by subclasses.
*
* @param body never <code>null</code>
* @param element never <code>null</code>
@@ -218,18 +217,19 @@
}
/**
- * Finds whether the given element has had a content change. This method is
- * called internally; it is not intended to be invoked by clients.
+ * Finds whether the given element has had a content change. Subclasses may
+ * override this method, but are not intended to invoke it.
* <p>
- * Implementations can compare the given bodies (excepting children)
- * and, if there are differences, insert an appropriate change delta
+ * Implementations can compare the given bodies and, if there are
+ * differences (excepting children), insert an appropriate change delta
* (such as <code>F_CONTENT</code>) for the given element into the delta
- * tree being built. Implementations should not take the element's
- * children into account.
+ * tree being built. Implementations should not take changes in children
+ * into account.
* </p>
* <p>
- * This implementation invokes <code>
- * ((Body)newBody).findContentChange((Body)oldBody, element, getDeltaBuilder())</code>.
+ * This implementation invokes <code>((Body)newBody).{@link
+ * Body#findContentChange(Body, IElement, IElementDeltaBuilder)
+ * findContentChange}((Body)oldBody, element, getDeltaBuilder())</code>.
* </p>
*
* @param oldBody the old version of the element's body (never <code>null</code>)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementDelta.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementDelta.java
index 819d2c9..3d43f57 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementDelta.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementDelta.java
@@ -511,7 +511,7 @@
* to its current location.
* <p>
* This is a low-level mutator method. In particular, it is the caller's
- * responsibility to set the appropriate kind and flags for this delta.
+ * responsibility to set appropriate kind and flags for this delta.
* </p>
*
* @param movedFromElement an element describing this delta's element
@@ -527,7 +527,7 @@
* Sets an element describing this delta's element in its new location.
* <p>
* This is a low-level mutator method. In particular, it is the caller's
- * responsibility to set the appropriate kind and flags for this delta.
+ * responsibility to set appropriate kind and flags for this delta.
* </p>
*
* @param movedToElement an element describing this delta's element
@@ -544,7 +544,7 @@
* the given array afterwards.
* <p>
* This is a low-level mutator method. In particular, it is the caller's
- * responsibility to set the appropriate kind and flags for this delta.
+ * responsibility to set appropriate kind and flags for this delta.
* </p>
*
* @param markerDeltas the marker deltas
@@ -560,7 +560,7 @@
* the given array afterwards.
* <p>
* This is a low-level mutator method. In particular, it is the caller's
- * responsibility to set the appropriate kind and flags for this delta.
+ * responsibility to set appropriate kind and flags for this delta.
* </p>
*
* @param resourceDeltas the resource deltas
@@ -575,7 +575,16 @@
/**
* Adds the given resource delta to the collection of resource deltas
- * of this delta.
+ * of this delta if permitted by the current state of this delta. Note
+ * that in contrast to {@link #setResourceDeltas_(IResourceDelta[])
+ * setResourceDeltas_}, this method can change this delta's kind and flags
+ * as appropriate.
+ * <p>
+ * If the kind of this delta is <code>ADDED</code> or <code>REMOVED</code>,
+ * this implementation returns without adding the given resource delta;
+ * otherwise, it sets the kind of this delta to <code>CHANGED</code> and
+ * adds the <code>F_CONTENT</code> change flag.
+ * </p>
*
* @param resourceDelta the resource delta to add (not <code>null</code>)
* @see #getResourceDeltas_()
@@ -617,7 +626,7 @@
/**
* Based on the given delta, creates a delta tree that can be directly
- * parented by this delta, and then {@link #addAffectedChild_ adds} the
+ * parented by this delta and {@link #addAffectedChild_ adds} the created
* tree as an affected child of this delta.
* <p>
* Note that after calling <code>insertSubTree_(delta)</code>
@@ -629,9 +638,9 @@
* </p>
* <pre> findDelta_(d.getElement_()) != null</pre>
* <p>
- * for any delta <code>d</code> in the subtree <code>delta</code>.
- * For example, if this delta tree already contains a delta
- * for <code>d.getElement_()</code>, that delta will be {@link
+ * for any delta <code>d</code> in the subtree <code>delta</code>
+ * (subtree root included). For example, if this delta tree already contains
+ * a delta for <code>d.getElement_()</code>, that delta will be {@link
* #mergeWith_(ElementDelta) merged} with <code>d</code>, which may even
* result in a logically empty delta, i.e., no delta for the element.
* </p>
@@ -646,10 +655,13 @@
}
/**
- * Adds the given delta as an affected child of this delta. If this delta
- * already contains a child delta for the same element as the given delta,
- * {@link #mergeWith_(ElementDelta) merges} the existing child delta with
- * the given delta.
+ * Adds the given delta as an affected child of this delta if permitted
+ * by the current state of this delta. If this delta already contains a
+ * child delta for the same element as the given delta, {@link #mergeWith_(
+ * ElementDelta) merges} the existing child delta with the given delta.
+ * Note that in contrast to {@link #setAffectedChildren_(ElementDelta[])
+ * setAffectedChildren_}, this method can change this delta's kind and flags
+ * as appropriate.
* <p>
* It is the caller's responsibility to ensure that the given delta can be
* directly parented by this delta.
@@ -664,7 +676,15 @@
* </p>
* <pre> findDelta_(d.getElement_()) != null</pre>
* <p>
- * for any delta <code>d</code> in the subtree <code>delta</code>.
+ * for any delta <code>d</code> in the subtree <code>delta</code>
+ * (subtree root included).
+ * </p>
+ * <p>
+ * If the kind of this delta is <code>ADDED</code> or <code>REMOVED</code>,
+ * this implementation returns without adding the given delta; otherwise,
+ * it sets the kind of this delta to <code>CHANGED</code> and adds the
+ * <code>F_CHILDREN</code> change flag and, if this delta's element is an
+ * {@link ISourceElement}, the <code>F_FINE_GRAINED</code> change flag.
* </p>
*
* @param child the delta to add as an affected child (not <code>null</code>)
@@ -836,10 +856,11 @@
}
/**
- * Sets the affected children for this delta.
+ * Sets the affected children for this delta. Clients <b>must not</b> modify
+ * the given array afterwards.
* <p>
* This is a low-level mutator method. In particular, it is the caller's
- * responsibility to set the appropriate kind and flags for this delta.
+ * responsibility to set appropriate kind and flags for this delta.
* </p>
*
* @param children the affected children (not <code>null</code>)
@@ -1105,11 +1126,9 @@
}
/**
- * {@inheritDoc}
- * <p>
- * This implementation always returns the root delta instance
- * specified in the constructor.
- * </p>
+ * Returns the root delta instance specified in the constructor.
+ *
+ * @return the root delta instance (never <code>null</code>)
*/
@Override
public ElementDelta getDelta()
@@ -1201,7 +1220,7 @@
rootDelta.mergeWith_(delta);
}
- /**
+ /*
* Returns a new <code>ADDED</code> delta for the given element.
*
* @param element the element that this delta describes a change to
@@ -1218,7 +1237,7 @@
return delta;
}
- /**
+ /*
* Returns a new <code>REMOVED</code> delta for the given element.
*
* @param element the element that this delta describes a change to
@@ -1235,7 +1254,7 @@
return delta;
}
- /**
+ /*
* Returns a new <code>CHANGED</code> delta for the given element.
*
* @param element the element that this delta describes a change to
@@ -1252,7 +1271,7 @@
return delta;
}
- /**
+ /*
* Returns a new "moved from" (<code>REMOVED</code>) delta for the
* given element.
*
@@ -1273,7 +1292,7 @@
return delta;
}
- /**
+ /*
* Returns a new "moved to" (<code>ADDED</code>) delta for the given
* element.
*
@@ -1295,20 +1314,20 @@
}
}
- /**
+ /*
* Represents a delta key.
* @see ElementDelta#childIndex
*/
private static class Key
{
- public final IElement element;
+ final IElement element;
- /**
+ /*
* Constructs a new delta key for the given element.
*
* @param element not <code>null</code>
*/
- public Key(IElement element)
+ Key(IElement element)
{
if (element == null)
throw new IllegalArgumentException();
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementManager.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementManager.java
index f2e8cc8..74c3407 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementManager.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ElementManager.java
@@ -82,10 +82,13 @@
* given context. If the current state of an open element does not permit
* closing (e.g., a working copy), it remains open. Closing of an element
* generally involves closing its children and removal of its body from the
- * body cache.
+ * body cache. This method is called under the element manager lock.
* <p>
- * This method is called internally; it is not intended to be invoked by clients.
- * This method is called under the element manager lock.
+ * Subclasses may override this method, but are not intended to invoke it.
+ * </p>
+ * <p>
+ * This implementation invokes <code>((IElementImplExtension)element).{@link
+ * IElementImplExtension#close_(IContext) close_}(context)</code>.
* </p>
*
* @param element the element that needs closing (never <code>null</code>)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/IElementDeltaBuilder.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/IElementDeltaBuilder.java
index 53ef3f8..6a2bd50 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/IElementDeltaBuilder.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/IElementDeltaBuilder.java
@@ -136,7 +136,7 @@
* Returns the root of the built delta tree. The delta tree describes
* the net result of all changes reported to this builder up to now.
* There is no requirement for the returned delta object to reflect
- * subsequent changes reported to this builder. Instead, a new instance
+ * subsequent changes reported to this builder; a new instance
* may be returned each time this method is invoked.
*
* @return the root of the built delta tree, or <code>null</code> if none
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/IElementImplSupport.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/IElementImplSupport.java
index 89af504..6504f00 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/IElementImplSupport.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/IElementImplSupport.java
@@ -85,7 +85,7 @@
* <p>
* By default, two elements that implement this interface are equal if they
* are identical or if they {@link #canEqual_(Object) can equal} each other
- * and both have equal names and parents. This method is specialized in
+ * and do have equal names and equal parents. This method is specialized in
* {@link ISourceConstructImplSupport} and {@link ISourceFileImplSupport}
* to also compare occurrence counts and underlying <code>IFile</code>s
* respectively. This method is not intended to be replaced by clients;
@@ -121,8 +121,8 @@
* instanceof</code> check.
* </p>
* <p>
- * For details, see <a href="http://www.artima.com/pins1ed/object-equality.html">
- * http://www.artima.com/pins1ed/object-equality.html</a>.
+ * For details, see <a href="https://www.artima.com/pins1ed/object-equality.html#28.2">
+ * https://www.artima.com/pins1ed/object-equality.html#28.2</a>, Pitfall #4.
* <p>
*
* @param obj not <code>null</code>
@@ -134,6 +134,12 @@
return getClass() == obj.getClass();
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation returns <code>getModelManager_().getModel()</code>.
+ * </p>
+ */
@Override
default IModel getModel_()
{
@@ -143,7 +149,10 @@
/**
* Returns the element manager for this element. The manager must be shared
* between all elements of a Handly-based model. Typical implementations
- * would answer a model-specific singleton.
+ * would answer a model-specific singleton. This is a handle-only method.
+ * <p>
+ * This implementation returns <code>getModelManager_().getElementManager()</code>.
+ * </p>
*
* @return the element manager for this element (never <code>null</code>)
*/
@@ -152,6 +161,13 @@
return getModelManager_().getElementManager();
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation returns <code>((Body)body).{@link Body#getChildren()
+ * getChildren()}</code>.
+ * </p>
+ */
@Override
default IElement[] getChildrenFromBody_(Object body)
{
@@ -170,6 +186,15 @@
return getElementManager_().peek(this);
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation returns <code>true</code> if there is a cached body
+ * for this element, and <code>false</code> if this element has a parent and
+ * the parent does not exist; otherwise, it invokes {@link #validateExistence_(
+ * IContext) validateExistence_} to determine the result.
+ * </p>
+ */
@Override
default boolean exists_()
{
@@ -190,7 +215,7 @@
}
/**
- * Validates if this element may be "opened", i.e., begin existence
+ * Validates that this element may be "opened", i.e., begin existence
* in the model. For example, a necessary condition for element existence
* might be that the underlying resource exists.
* <p>
@@ -218,6 +243,22 @@
toDisplayString_(of(FORMAT_STYLE, FULL))), null));
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation attempts to {@link #openParent_(IContext,
+ * IProgressMonitor) open} the parent element first. Then, if this element
+ * is {@link #isOpenable_() openable} and is {@link #validateExistence_(
+ * IContext) permitted} to open, invokes {@link #buildStructure_(IContext,
+ * IProgressMonitor)} with an appropriately augmented context, acquires the
+ * element manager lock, updates the body cache with the built structure,
+ * and releases the lock. When this element is already open, the update may
+ * involve closing existing children or do nothing at all, depending on the
+ * value of <code>FORCE_OPEN</code>. If this element is not openable
+ * and the openable parent did not create a body for this element,
+ * this implementation throws a {@link #newDoesNotExistException_()}.
+ * </p>
+ */
@Override
default Object open_(IContext context, IProgressMonitor monitor)
throws CoreException
@@ -275,19 +316,25 @@
}
/**
- * Open the parent element if necessary.
+ * Opens the parent element if necessary.
* <p>
* This method is called internally; it is not intended to be invoked
* by clients.
* </p>
+ * <p>
+ * This implementation attempts to {@link #open_(IContext, IProgressMonitor)
+ * open} the parent element if it supports {@link IElementImplExtension} and
+ * is not already open.
+ * </p>
*
- * @param context the operation context (not <code>null</code>)
- * @param monitor a progress monitor (not <code>null</code>).
+ * @param context the operation context (never <code>null</code>)
+ * @param monitor a progress monitor (never <code>null</code>).
* The caller must not rely on {@link IProgressMonitor#done()}
* having been called by the receiver
* @throws CoreException if an exception occurs while opening this element's
* parent
* @throws OperationCanceledException if this method is canceled
+ * @see #open_(IContext, IProgressMonitor)
*/
default void openParent_(IContext context, IProgressMonitor monitor)
throws CoreException
@@ -302,14 +349,13 @@
}
/**
- * Returns whether this element is "openable".
- * <p>
- * An openable element knows how to open itself on demand (i.e., initialize
- * its body and put it in the body cache). When opening an element, it is
- * ensured that all openable parent elements are open. On the other hand,
- * opening an element should open only those child elements that are not
- * openable: all other children will open themselves on demand.
- * </p>
+ * Returns whether this element is "openable". Openable elements know
+ * how to {@link #buildStructure_(IContext, IProgressMonitor) build} their
+ * structure and can be {@link #open_(IContext, IProgressMonitor) opened}
+ * one by one. In particular, there is no need to open an openable child
+ * when opening its parent. Non-openable elements rely on the openable
+ * parent to build their structure. Opening of a parent element opens all
+ * non-openable children at once.
* <p>
* This implementation returns <code>true</code>. Non-openable elements
* must override this method and return <code>false</code>.
@@ -339,6 +385,11 @@
* #isOpenable_() openable} child element (and their non-openable children,
* recursively). Uses the {@link #NEW_ELEMENTS} map in the given context
* to associate the created bodies with their respective elements.
+ * <p>
+ * Note that this method does not make sense and must not be called for
+ * non-openable elements -- they rely on the openable parent to build their
+ * structure.
+ * </p>
*
* @param context the operation context (not <code>null</code>)
* @param monitor a progress monitor (not <code>null</code>).
@@ -354,7 +405,7 @@
* {@inheritDoc}
* <p>
* After checking that the current state of this element permits closing,
- * this implementation invokes {@link #remove_(IContext)} method to actually
+ * this implementation invokes {@link #remove_(IContext)} to actually
* close this element.
* </p>
*/
@@ -371,7 +422,7 @@
* Removes this element from the body cache according to options specified
* in the given context. In general, not only removes the cached body for this
* element but also attempts to close this element's children. Does nothing
- * if the cache contained no body for this element. Performs atomically.
+ * if the cache contained no body for this element.
* <p>
* This is a low-level operation, which removes this element's body and
* thus closes this element even if the current state of this element does
@@ -393,14 +444,13 @@
}
/**
- * The cached body for this element is going to be removed from the body cache.
- * Do any necessary cleanup.
+ * Informs this element that its body is going to be removed from the body cache.
+ * This method is called under the element manager lock.
* <p>
* This method is called internally; it is not intended to be invoked by clients.
- * This method is called under the element manager lock.
* </p>
*
- * @param body the cached body for this element (not <code>null</code>)
+ * @param body the cached body for this element (never <code>null</code>)
*/
default void removing_(Object body)
{
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/INotificationManager.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/INotificationManager.java
index a90c3f6..846a9fa 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/INotificationManager.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/INotificationManager.java
@@ -25,7 +25,7 @@
/**
* Notifies registered listeners about the given event.
*
- * @param event the change event (not <code>null</code>)
+ * @param event an element change event (not <code>null</code>)
*/
void fireElementChangeEvent(IElementChangeEvent event);
}
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceConstructImplSupport.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceConstructImplSupport.java
index 5c252d1..7017fb5 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceConstructImplSupport.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceConstructImplSupport.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2014, 2017 1C-Soft LLC and others.
+ * Copyright (c) 2014, 2018 1C-Soft LLC and others.
*
* This program and the accompanying materials are made available under
* the terms of the Eclipse Public License 2.0 which is available at
@@ -48,6 +48,18 @@
&& ISourceElementImplSupport.super.defaultEquals_(obj);
}
+ /**
+ * Returns whether this element exists in the model.
+ * <p>
+ * Handles may or may not be backed by an actual element. Handles that are
+ * backed by an actual element are said to "exist".
+ * </p>
+ * <p>
+ * This implementation returns <code>true</code> if there is a cached body
+ * for this element; otherwise, attempts to {@link #open_(IContext,
+ * IProgressMonitor) open} this element to determine the result.
+ * </p>
+ */
@Override
default boolean exists_()
{
@@ -63,20 +75,7 @@
}
/**
- * Returns whether this element is "openable".
- * <p>
- * An openable element knows how to open itself on demand (i.e. initialize
- * its body and put it in the body cache). When opening an element, it is
- * ensured that all openable parent elements are open. On the other hand,
- * opening an element should open only those child elements that are not
- * openable: all other children will open themselves on demand.
- * </p>
- * <p>
* This implementation always returns <code>false</code>.
- * </p>
- *
- * @return <code>true</code> if this element is openable,
- * <code>false</code> otherwise
*/
@Override
default boolean isOpenable_()
@@ -85,11 +84,8 @@
}
/**
- * {@inheritDoc}
- * <p>
* This implementation throws assertion error; the openable parent builds
* the whole structure and determines child existence.
- * </p>
*/
@Override
default void validateExistence_(IContext context) throws CoreException
@@ -98,11 +94,8 @@
}
/**
- * {@inheritDoc}
- * <p>
* This implementation throws assertion error; the openable parent builds
* the whole structure in one go.
- * </p>
*/
@Override
default void buildStructure_(IContext context, IProgressMonitor monitor)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceElementImplSupport.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceElementImplSupport.java
index 7587201..ca370ef 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceElementImplSupport.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceElementImplSupport.java
@@ -18,6 +18,7 @@
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;
+import org.eclipse.core.runtime.OperationCanceledException;
import org.eclipse.core.runtime.SubMonitor;
import org.eclipse.handly.context.IContext;
import org.eclipse.handly.model.Elements;
@@ -42,6 +43,16 @@
public interface ISourceElementImplSupport
extends IElementImplSupport, ISourceElementImpl
{
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation delegates to {@link #getBody_(IContext,
+ * IProgressMonitor)}; it is assumed that the body implements
+ * {@link ISourceElementInfo}.
+ * </p>
+ * @throws CoreException {@inheritDoc}
+ * @throws OperationCanceledException {@inheritDoc}
+ */
@Override
default ISourceElementInfo getSourceElementInfo_(IContext context,
IProgressMonitor monitor) throws CoreException
@@ -56,14 +67,11 @@
* delegates to {@link #getSourceElementAt_(int, ISourceElementInfo, IContext,
* IProgressMonitor)} if the given position is within the source range of
* this element as reported by {@link #checkInRange(int, ISourceElementInfo,
- * IContext)}. Otherwise, returns <code>null</code>.
+ * IContext)}; otherwise, <code>null</code> is returned.
* </p>
- *
- * @throws CoreException if this element does not exist or if an
- * exception occurs while accessing its corresponding resource
- * @throws StaleSnapshotException if snapshot inconsistency is detected,
- * i.e., this element's current structure and properties are based on
- * a different snapshot
+ * @throws CoreException {@inheritDoc}
+ * @throws StaleSnapshotException {@inheritDoc}
+ * @throws OperationCanceledException {@inheritDoc}
*/
@Override
default ISourceElement getSourceElementAt_(int position, IContext context,
@@ -83,9 +91,21 @@
* given source position, which is known to be within the source range of
* this element as recorded by the given element info. If no finer grained
* element is found at the position, this element itself is returned.
+ * <p>
+ * Implementations are encouraged to support the following standard options,
+ * which may be specified in the given context:
+ * </p>
+ * <ul>
+ * <li>
+ * {@link org.eclipse.handly.model.Elements#BASE_SNAPSHOT BASE_SNAPSHOT} -
+ * A snapshot on which the given position is based, or <code>null</code>
+ * if the snapshot is unknown or does not matter.
+ * </li>
+ * </ul>
*
* @param position a source position (0-based)
- * @param info the info object for this element (not <code>null</code>)
+ * @param info an {@link ISourceElementInfo} for this element
+ * (not <code>null</code>)
* @param context the operation context (not <code>null</code>)
* @param monitor a progress monitor (not <code>null</code>).
* The caller must not rely on {@link IProgressMonitor#done()}
@@ -95,6 +115,7 @@
* @throws CoreException if an exception occurs while accessing
* the element's corresponding resource
* @throws StaleSnapshotException if snapshot inconsistency is detected
+ * @throws OperationCanceledException if this method is canceled
*/
default ISourceElement getSourceElementAt_(int position,
ISourceElementInfo info, IContext context, IProgressMonitor monitor)
@@ -122,9 +143,20 @@
/**
* Checks whether the given position is within the element's range
* in the source snapshot as recorded by the given element info.
+ * <p>
+ * Supports the following standard options, which may be specified
+ * in the given context:
+ * </p>
+ * <ul>
+ * <li>
+ * {@link org.eclipse.handly.model.Elements#BASE_SNAPSHOT BASE_SNAPSHOT} -
+ * A snapshot on which the given position is based, or <code>null</code>
+ * if the snapshot is unknown or does not matter.
+ * </li>
+ * </ul>
*
* @param position a source position (0-based)
- * @param info the source element info (not <code>null</code>)
+ * @param info an {@link ISourceElementInfo} (not <code>null</code>)
* @param context the operation context (not <code>null</code>)
* @return <code>true</code> if the given position is within the element's
* source range, and <code>false</code> otherwise
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceFileImplSupport.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceFileImplSupport.java
index ae4147f..14dbf61 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceFileImplSupport.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/ISourceFileImplSupport.java
@@ -42,6 +42,7 @@
import org.eclipse.handly.model.IElement;
import org.eclipse.handly.model.IElementDelta;
import org.eclipse.handly.model.impl.DefaultWorkingCopyCallback;
+import org.eclipse.handly.model.impl.IElementImplExtension;
import org.eclipse.handly.model.impl.IReconcileStrategy;
import org.eclipse.handly.model.impl.ISourceFileImplExtension;
import org.eclipse.handly.model.impl.IWorkingCopyCallback;
@@ -202,6 +203,14 @@
return getWorkingCopyContext_() != null;
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation delegates to the namesake method of the working copy
+ * callback, provided that this source file is a working copy.
+ * </p>
+ * @see IWorkingCopyCallback#needsReconciling()
+ */
@Override
default boolean needsReconciling_()
{
@@ -227,6 +236,16 @@
}
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation delegates to the namesake method of the working copy
+ * callback, provided that this source file is a working copy.
+ * </p>
+ * @throws CoreException {@inheritDoc}
+ * @throws OperationCanceledException {@inheritDoc}
+ * @see IWorkingCopyCallback#reconcile(IContext, IProgressMonitor)
+ */
@Override
default void reconcile_(IContext context, IProgressMonitor monitor)
throws CoreException
@@ -257,15 +276,15 @@
/**
* Returns a reconcile operation for this source file.
* <p>
- * This implementation returns a new instance of {@link
- * NotifyingReconcileOperation} if there is a notification manager
- * registered in the model context. Otherwise, a new instance of
- * {@link ReconcileOperation} is returned.
- * </p>
- * <p>
* This method is called internally; it is not intended to be invoked by
* clients.
* </p>
+ * <p>
+ * This implementation returns a new instance of {@link
+ * NotifyingReconcileOperation} if there is a notification manager
+ * registered in the model context; otherwise, a new instance of
+ * {@link ReconcileOperation} is returned.
+ * </p>
*
* @return a reconcile operation for this source file
* (never <code>null</code>)
@@ -282,7 +301,7 @@
/**
* Returns a context to be associated with a new working copy of this
* source file. The given operation context is propagated from the
- * {@link #becomeWorkingCopy_} method.
+ * {@link #becomeWorkingCopy_(IContext, IProgressMonitor)} method.
* <p>
* The returned context is composed of the context explicitly {@link
* ISourceFileImplExtension#WORKING_COPY_CONTEXT specified} when creating
@@ -290,15 +309,16 @@
* in that order.
* </p>
* <p>
- * This implementation returns <code>context.getOrDefault(WORKING_COPY_CONTEXT)</code>.
- * </p>
- * <p>
* This method is called internally; it is not intended to be invoked by
* clients.
* </p>
+ * <p>
+ * This implementation returns <code>context.getOrDefault(WORKING_COPY_CONTEXT)</code>.
+ * </p>
*
- * @param context the operation context (not <code>null</code>)
+ * @param context the operation context (never <code>null</code>)
* @return the working copy context (never <code>null</code>)
+ * @see #getWorkingCopyContext_()
*/
default IContext newWorkingCopyContext_(IContext context)
{
@@ -306,17 +326,20 @@
}
/**
- * Notifies about a working copy mode change: either the source file
- * became a working copy or reverted back from the working copy mode.
- * <p>
- * This implementation does nothing if no notification manager is
- * registered in the model context. Otherwise, it sends out a delta
- * notification indicating the nature of the working copy mode change.
- * </p>
+ * Informs this source file about a working copy mode change: either
+ * the source file became a working copy or reverted back from the
+ * working copy mode.
* <p>
* This method is called internally; it is not intended to be invoked by
* clients.
* </p>
+ * <p>
+ * This implementation sends out a delta notification indicating the nature
+ * of the working copy mode change, provided that a notification manager is
+ * registered in the model context.
+ * </p>
+ *
+ * @see INotificationManager
*/
default void workingCopyModeChanged_()
{
@@ -403,7 +426,7 @@
}
/**
- * Returns the buffer opened for the underlying file of this source file.
+ * Returns a buffer opened for the underlying file of this source file.
* Note that buffers may be shared by multiple clients, so the returned buffer
* may have unsaved changes if it has been modified by another client.
* <p>
@@ -413,18 +436,25 @@
* be accessed by clients which do not own it.
* </p>
* <p>
+ * A new object may be returned, even for the same underlying buffer,
+ * each time this method is invoked.
+ * </p>
+ * <p>
* Implementations are encouraged to support the following standard options,
* which may be specified in the given context:
* </p>
* <ul>
* <li>
* {@link org.eclipse.handly.model.Elements#CREATE_BUFFER CREATE_BUFFER} -
- * Indicates whether a new buffer should be created if none already exists.
+ * Indicates whether a new buffer should be created if none already exists
+ * for the underlying file.
* </li>
* </ul>
* <p>
- * This implementation returns the buffer opened for the underlying
- * {@link #getFile_() IFile}; it throws an assertion error if this source file
+ * This implementation returns a buffer opened for the underlying {@link
+ * #getFile_() IFile}, or <code>null</code> if <code>CREATE_BUFFER</code> is
+ * <code>false</code> in the given context and there is currently no buffer
+ * opened for that file; it throws an assertion error if this source file
* has no underlying file in the workspace.
* </p>
*
@@ -432,9 +462,9 @@
* @param monitor a progress monitor, or <code>null</code>
* if progress reporting is not desired. The caller must not rely on
* {@link IProgressMonitor#done()} having been called by the receiver
- * @return the buffer opened for the underlying file of this source file,
- * or <code>null</code> if <code>CREATE_BUFFER == false</code> and
- * there is currently no buffer opened for that file
+ * @return a buffer opened for the underlying file of this source file,
+ * or <code>null</code> if <code>CREATE_BUFFER</code> is <code>false</code>
+ * in the given context and there is currently no buffer opened for that file
* @throws CoreException if the buffer could not be opened
* @throws OperationCanceledException if this method is canceled
*/
@@ -455,6 +485,14 @@
return new TextFileBuffer(provider, monitor);
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation does nothing if this source file is a working copy;
+ * otherwise, it throws a {@link #newDoesNotExistException_()} if the
+ * underlying file does not {@link #fileExists_() exist}.
+ * </p>
+ */
@Override
default void validateExistence_(IContext context) throws CoreException
{
@@ -465,6 +503,21 @@
}
}
+ /**
+ * Opens the parent element if necessary.
+ * <p>
+ * This method is called internally; it is not intended to be invoked
+ * by clients.
+ * </p>
+ * <p>
+ * This implementation does nothing if this source file is a working copy;
+ * otherwise, it attempts to {@link #open_(IContext, IProgressMonitor) open}
+ * the parent element if it supports {@link IElementImplExtension} and
+ * is not already open.
+ * </p>
+ * @throws CoreException {@inheritDoc}
+ * @throws OperationCanceledException {@inheritDoc}
+ */
@Override
default void openParent_(IContext context, IProgressMonitor monitor)
throws CoreException
@@ -474,6 +527,20 @@
ISourceElementImplSupport.super.openParent_(context, monitor);
}
+ /**
+ * This implementation delegates to {@link #buildSourceStructure_(IContext,
+ * IProgressMonitor)} with an appropriately augmented context. In particular,
+ * if the given context contains neither {@link #SOURCE_CONTENTS} nor {@link
+ * #SOURCE_AST}, it is augmented with {@link #SOURCE_CONTENTS} and the
+ * corresponding {@link #SOURCE_SNAPSHOT} obtained from the underlying
+ * file's {@link #getFileSnapshotProvider_() stored contents}. Also,
+ * performs some post-processing of created {@link SourceElementBody}s
+ * to complete their initialization, such as setting the source snapshot
+ * on which they are based.
+ *
+ * @throws CoreException {@inheritDoc}
+ * @throws OperationCanceledException {@inheritDoc}
+ */
@Override
default void buildStructure_(IContext context, IProgressMonitor monitor)
throws CoreException
@@ -595,6 +662,12 @@
void buildSourceStructure_(IContext context, IProgressMonitor monitor)
throws CoreException;
+ /**
+ * {@inheritDoc}
+ * <p>
+ * Note that a working copy is never permitted to close.
+ * </p>
+ */
@Override
default void close_(IContext context)
{
@@ -620,8 +693,8 @@
* This class or a subclass of this class are not intended to be used by
* clients for purposes other than extension or instance creation;
* instances of this class or a subclass of this class are not intended
- * to be used by clients for purposes other than returning from {@link
- * ISourceFileImplSupport#getReconcileOperation_() getReconcileOperation_()}.
+ * to be used by clients for purposes other than returning from an
+ * implementation of {@link ISourceFileImplSupport#getReconcileOperation_()}.
* </p>
*
* @see NotifyingReconcileOperation
@@ -856,8 +929,8 @@
* This class or a subclass of this class are not intended to be used by
* clients for purposes other than extension or instance creation;
* instances of this class or a subclass of this class are not intended
- * to be used by clients for purposes other than returning from {@link
- * ISourceFileImplSupport#getReconcileOperation_() getReconcileOperation_()}.
+ * to be used by clients for purposes other than returning from an
+ * implementation of {@link ISourceFileImplSupport#getReconcileOperation_()}.
* </p>
*
* @see INotificationManager
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/NotificationManager.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/NotificationManager.java
index 2247126..a761678 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/NotificationManager.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/NotificationManager.java
@@ -49,8 +49,8 @@
* event types.
* <p>
* After completion of this method, the given listener will be registered
- * for exactly the specified event types. If they were previously registered
- * for other event types, they will be de-registered.
+ * for exactly the specified event types. If it was previously registered
+ * for other event types, it will be de-registered for those event types.
* </p>
*
* @param listener the listener to add (not <code>null</code>)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/SourceElementBody.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/SourceElementBody.java
index d75789c..75eed80 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/SourceElementBody.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/SourceElementBody.java
@@ -167,6 +167,18 @@
this.identifyingRange = identifyingRange;
}
+ /**
+ * {@inheritDoc}
+ * <p>
+ * This implementation inserts a change delta with flags
+ * <code>F_CONTENT</code> and <code>F_FINE_GRAINED</code> if there is
+ * a {@link #isPropertyChanged(String, Object, Object) change} in the
+ * {@link #getPropertyValue(String) value} of one of the element's
+ * {@link #getPropertyNames() properties}. For a source file, this
+ * implicitly includes a change in its source {@link #getFullRange()
+ * range} or {@link #getSnapshot() snapshot}.
+ * </p>
+ */
@Override
public void findContentChange(Body oldBody, IElement element,
IElementDeltaBuilder builder)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/SourceFile.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/SourceFile.java
index ab5e0a7..d55d77b 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/SourceFile.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/SourceFile.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2014, 2017 1C-Soft LLC and others.
+ * Copyright (c) 2014, 2018 1C-Soft LLC and others.
*
* This program and the accompanying materials are made available under
* the terms of the Eclipse Public License 2.0 which is available at
@@ -13,13 +13,13 @@
package org.eclipse.handly.model.impl.support;
import org.eclipse.handly.model.IElement;
-import org.eclipse.handly.model.impl.ISourceFileImpl;
+import org.eclipse.handly.model.impl.ISourceFileImplExtension;
/**
- * Provides a skeletal implementation of {@link ISourceFileImpl} to minimize
- * the effort required to implement that interface. Clients might as well
- * implement ("mix in") {@link ISourceFileImplSupport} directly if extending
- * this class is not possible/desirable for some reason.
+ * Provides a skeletal implementation of {@link ISourceFileImplExtension}
+ * to minimize the effort required to implement that interface. Clients might
+ * as well implement ("mix in") {@link ISourceFileImplSupport} directly
+ * if extending this class is not possible/desirable for some reason.
*
* @see WorkspaceSourceFile
*/
diff --git a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/WorkspaceSourceFile.java b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/WorkspaceSourceFile.java
index 379fae8..02812d9 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/WorkspaceSourceFile.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/model/impl/support/WorkspaceSourceFile.java
@@ -15,13 +15,13 @@
import org.eclipse.core.resources.IFile;
import org.eclipse.core.resources.IResource;
import org.eclipse.handly.model.IElement;
-import org.eclipse.handly.model.impl.ISourceFileImpl;
+import org.eclipse.handly.model.impl.ISourceFileImplExtension;
/**
- * Provides a skeletal implementation of {@link ISourceFileImpl} for source files
- * residing in the workspace. Such files always have an underlying {@link IFile}.
- * This class is just an implementation convenience. Clients might as well
- * implement a workspace source file by extending {@link SourceFile} or
+ * Provides a skeletal implementation of {@link ISourceFileImplExtension} for
+ * source files residing in the workspace. Such files always have an underlying
+ * {@link IFile}. This class is just an implementation convenience. Clients might
+ * as well implement a workspace source file by extending {@link SourceFile} or
* implementing ("mixing in") {@link ISourceFileImplSupport} directly
* if extending this class is not possible/desirable for some reason.
*/
@@ -44,6 +44,11 @@
this.file = file;
}
+ /**
+ * Returns the underlying {@link IFile}. This is a handle-only method.
+ *
+ * @return the underlying <code>IFile</code> (never <code>null</code>)
+ */
@Override
public final IResource getResource_()
{
diff --git a/org.eclipse.handly/src/org/eclipse/handly/snapshot/ISnapshot.java b/org.eclipse.handly/src/org/eclipse/handly/snapshot/ISnapshot.java
index 4bf82b5..7498a7b 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/snapshot/ISnapshot.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/snapshot/ISnapshot.java
@@ -14,7 +14,7 @@
/**
* A snapshot of the character contents of a resource or buffer.
- * The client may hold on a snapshot for an extended period of time,
+ * Clients may hold on snapshots for extended periods of time,
* but a snapshot may 'expire' if the underlying resource or buffer
* has changed or ceased to exist since the snapshot inception.
* <p>
diff --git a/org.eclipse.handly/src/org/eclipse/handly/snapshot/ISnapshotProvider.java b/org.eclipse.handly/src/org/eclipse/handly/snapshot/ISnapshotProvider.java
index 49e7845..52e8ef1 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/snapshot/ISnapshotProvider.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/snapshot/ISnapshotProvider.java
@@ -20,9 +20,9 @@
* <p>
* Snapshot providers support {@link IReferenceCountable} protocol, although
* some implementations do not have a need in reference counting and inherit
- * a no-op implementation of the protocol methods. When it is known that
- * a snapshot provider does not actually use reference counting, clients
- * do not need to follow the requirements set forth in that protocol.
+ * a no-op implementation of the protocol methods in this interface. When it
+ * is known that a snapshot provider does not actually use reference counting,
+ * clients do not need to follow the requirements set forth in that protocol.
* </p>
* <p>
* Snapshot providers are generally designed to be safe for use by multiple
diff --git a/org.eclipse.handly/src/org/eclipse/handly/snapshot/TextFileSnapshotBase.java b/org.eclipse.handly/src/org/eclipse/handly/snapshot/TextFileSnapshotBase.java
index 3ad0abf..e6d68df 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/snapshot/TextFileSnapshotBase.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/snapshot/TextFileSnapshotBase.java
@@ -64,7 +64,7 @@
* Returns whether the file existed at the moment this snapshot was taken.
*
* @return <code>true</code> if the file existed at the moment this snapshot
- * was taken, <code>false</code> otherwise
+ * was taken, and <code>false</code> otherwise
*/
public abstract boolean exists();
diff --git a/org.eclipse.handly/src/org/eclipse/handly/snapshot/TextFileSnapshotWs.java b/org.eclipse.handly/src/org/eclipse/handly/snapshot/TextFileSnapshotWs.java
index 00f04e6..caad99c 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/snapshot/TextFileSnapshotWs.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/snapshot/TextFileSnapshotWs.java
@@ -43,7 +43,7 @@
*
* @param file not <code>null</code>
*/
- public TextFileSnapshotWs(IFile file)
+ TextFileSnapshotWs(IFile file)
{
if (file == null)
throw new IllegalArgumentException();
diff --git a/org.eclipse.handly/src/org/eclipse/handly/util/ArrayUtil.java b/org.eclipse.handly/src/org/eclipse/handly/util/ArrayUtil.java
index 034fd9a..7440211 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/util/ArrayUtil.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/util/ArrayUtil.java
@@ -23,7 +23,7 @@
/**
* Provides static utility methods for manipulating arrays. These utilities
- * supplement those found in {@link Arrays}.
+ * supplement those found in {@link java.util.Arrays}.
*/
public class ArrayUtil
{
diff --git a/org.eclipse.handly/src/org/eclipse/handly/util/IReferenceCountable.java b/org.eclipse.handly/src/org/eclipse/handly/util/IReferenceCountable.java
index a270c0e..f2386f0 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/util/IReferenceCountable.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/util/IReferenceCountable.java
@@ -13,13 +13,10 @@
package org.eclipse.handly.util;
/**
- * A common protocol for reference countable objects.
- * <p>
- * A reference countable object may be shared by multiple clients and
- * will be disposed only after it is released by every owner. Clients which
- * do not own the object must not access it; attempting that will result
- * in unspecified behavior.
- * </p>
+ * A common protocol for reference countable objects. A reference countable
+ * object may be shared by multiple clients and will be disposed only after
+ * it is released by every owner. Clients which do not own the object must not
+ * access it; attempting that will result in unspecified behavior.
*/
public interface IReferenceCountable
extends AutoCloseable
diff --git a/org.eclipse.handly/src/org/eclipse/handly/util/LruCache.java b/org.eclipse.handly/src/org/eclipse/handly/util/LruCache.java
index a4e9b10..982dc86 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/util/LruCache.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/util/LruCache.java
@@ -17,11 +17,11 @@
import java.util.Map;
/**
- * An LRU cache without a maximum size (i.e., unbounded). Entries are ordered
- * in the cache from most recently accessed to least recently accessed.
- * When a cache entry is accessed via {@link #get(Object) get} or {@link
- * #put(Object, Object) put} methods, it is moved to the most recently used
- * position in the cache. No other public methods generate entry accesses.
+ * An LRU cache. Entries are ordered in the cache from most recently accessed
+ * to least recently accessed. When a cache entry is accessed via {@link
+ * #get(Object) get} or {@link #put(Object, Object) put} methods, it is moved
+ * to the most recently used position in the cache. No other public methods
+ * generate entry accesses.
*/
public class LruCache<K, V>
{
diff --git a/org.eclipse.handly/src/org/eclipse/handly/util/Property.java b/org.eclipse.handly/src/org/eclipse/handly/util/Property.java
index 2e4506d..2ddc2f8 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/util/Property.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/util/Property.java
@@ -29,7 +29,7 @@
* relations need to be specified on a case-by-case basis.
* </p>
*
- * @param <T> the type of property values
+ * @param <T> the type of the property
*/
public class Property<T>
{
@@ -38,7 +38,7 @@
private final Class<T> rawType;
/**
- * Constructs a new property with the given name. The type information
+ * Constructs a property with the given name. The type information
* is captured implicitly.
* <p>
* The protected constructor forces clients to create a subclass
@@ -94,7 +94,7 @@
* @param name the name of the property (not <code>null</code>)
* @param type the type of the property (not <code>null</code>)
* @return a property with the given name and type (never <code>null</code>)
- * @param <T> the type of property values
+ * @param <T> the type of the property
*/
public static <T> Property<T> get(String name, Class<T> type)
{
diff --git a/org.eclipse.handly/src/org/eclipse/handly/util/SavedStateJob.java b/org.eclipse.handly/src/org/eclipse/handly/util/SavedStateJob.java
index 0fc1e68..f03a282 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/util/SavedStateJob.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/util/SavedStateJob.java
@@ -40,7 +40,7 @@
*
* @param pluginId the unique identifier of the plug-in
* (not <code>null</code>)
- * @param listener the resource change listener to process a <code>POST-BUILD</code>
+ * @param listener the resource change listener to process a <code>POST_BUILD</code>
* event supplied by the saved state for the given plug-in (not <code>null</code>)
*/
public SavedStateJob(String pluginId, IResourceChangeListener listener)
diff --git a/org.eclipse.handly/src/org/eclipse/handly/util/TextRange.java b/org.eclipse.handly/src/org/eclipse/handly/util/TextRange.java
index ff1050e..56fe5de 100644
--- a/org.eclipse.handly/src/org/eclipse/handly/util/TextRange.java
+++ b/org.eclipse.handly/src/org/eclipse/handly/util/TextRange.java
@@ -13,8 +13,8 @@
package org.eclipse.handly.util;
/**
- * Describes a certain range in an indexed text store. Text stores are
- * for example documents or strings. A text range is defined by its offset
+ * Describes a certain range in an indexed text store. Text stores are,
+ * for example, documents or strings. A text range is defined by its offset
* into the text store and its length. A text range is a value object.
* Its offset and length do not change over time.
*/
@@ -24,7 +24,7 @@
private final int length;
/**
- * Constructs a text range using the given offset and the given length.
+ * Constructs a text range with the given offset and the given length.
*
* @param offset the given offset (0-based)
* @param length the given length (non-negative)
