cleanup and further comments
diff --git a/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IModelManagerProposed.java b/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IModelManagerProposed.java
index bf69585..5621de2 100644
--- a/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IModelManagerProposed.java
+++ b/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IModelManagerProposed.java
@@ -22,31 +22,31 @@
 import org.eclipse.wst.sse.core.exceptions.ResourceInUse;
 import org.eclipse.wst.sse.core.text.IStructuredDocument;
 
-
 /**
- * Responsible for managing structured models.
+ * Responsible for managing IStructuredModels.
  * 
  * This allows clients to share models, so they do not have to be re-created
- * or "passed around" from one client to another. There is a heavy burden on
- * clients, though, in that every client who 'gets' a model must correctly
- * 'release' it.
+ * or passed around from one client to another. Clients should internally
+ * enforce that models are gotten and released from locations close to each
+ * other to prevent model leaks.
  * 
- * There are two ways to get a model, for 'EDIT' or for 'READ'. Contrary to
- * their names, either model can, technically, be modified, and when modified,
- * it modifies the commonily shared version of the model. It is part of the
- * API contract however, that clients who get a model for READ do not modify
- * it. The significance of the 'EDIT' model is that the client is registering
- * their interest in saving changes to the model.
+ * There are three ways to get a model based on usage and responsibility: for
+ * 'WRITE', just for 'SHARED', and 'UNSHARED'. Contrary to their names, a
+ * model can technically be modified, and all modifications directly affect
+ * the commonly shared version of the model. It is part of the API contract,
+ * however, that clients who get a model for SHARED do not modify it. The
+ * significance of the 'WRITE' model is that the client is registering their
+ * interest in saving changes to the model.
  * 
  * Clients can reference this interface, but should not implement.
  * 
- * @see StructuredModelManger
+ * @see StructuredModelManager
  * @since 1.0
  */
 public interface IModelManagerProposed {
 
 	/**
-	 * ReadEditType is used internally to create. Not intented to be
+	 * ReadEditType is used internally to create. Not intended to be
 	 * referenced by clients.
 	 */
 	static class ReadEditType {
@@ -71,64 +71,26 @@
 	}
 
 	/**
-	 * Constant to provide compile time safe paramenter. <code>EDIT</code>signifies
-	 * the client is intending to make changes and is responsible for saving
-	 * changes (or not) if they are the last one holding the model before its
-	 * released.
-	 */
-	final ReadEditType WRITE = new ReadEditType("WRITE"); //$NON-NLS-1$
-	/**
-	 * Constant to provide compile time safe paramenter. <code>READ</code>signifies
-	 * the client is not intending to make changes and does not care about the
-	 * saved state of the model.
-	 */
-	final ReadEditType SHARED = new ReadEditType("SHARED"); //$NON-NLS-1$
-	/**
-	 * Constant to provide compile time safe paramenter.
-	 * <code>NOTSHARED</code>signifies the client intentially wants a model
-	 * that is not shared with other clients. Note: NOTSHARED models can not
-	 * be saved.
+	 * Constant to provide compile time safe parameter. <code>NOTSHARED</code>signifies
+	 * the client intentially wants a model that is not shared with other
+	 * clients. NOTSHARED models can not be saved.
 	 */
 	final ReadEditType NOTSHARED = new ReadEditType("NOTSHARED"); //$NON-NLS-1$
 
 	/**
-	 * createNewInstance is similar to clone, except the new instance has no
-	 * text content. Note: this produces an UNSHARED model, for temporary use,
-	 * that has the same characteristics as original model. If a true shared
-	 * model is desired, use "copy".
-	 * 
-	 * ISSUE: still needed?
+	 * Constant to provide compile-time safe parameter. <code>SHARED</code>signifies
+	 * the client is not intending to make changes and does not care whether
+	 * the model accessed is saved.
 	 */
-	public IStructuredModel createNewInstance(Object requester, IStructuredModel model) throws IOException;
+	final ReadEditType SHARED = new ReadEditType("SHARED"); //$NON-NLS-1$
 
 	/**
-	 * Returns the model, if it already exists and is being shared. Returns
-	 * null if this is not the case.
-	 * 
-	 * @param location
-	 * @param type
-	 * @return
+	 * Constant to provide compile-time safe parameter. <code>WRITE</code>signifies
+	 * the client is intending to make changes and is responsible for saving
+	 * changes (or not) if they are the last one holding WRITE access to the
+	 * model before it's released.
 	 */
-	public IStructuredModel getExistingModel(Object requester, ReadEditType type, IPath location);
-
-	/**
-	 * Returns the model that has the specified document as its core text
-	 * buffer.
-	 * 
-	 * @param document
-	 * @param type
-	 * @return
-	 */
-	public IStructuredModel getModel(Object requester, ReadEditType type, IProgressMonitor progressMonitor, IDocument document);
-
-	/**
-	 * Returns the model based on the content at the specified location.
-	 * 
-	 * @param location
-	 * @param type
-	 * @return
-	 */
-	public IStructuredModel getModel(Object requester, ReadEditType type, IProgressMonitor progressMonitor, IPath location) throws IOException, CoreException;
+	final ReadEditType WRITE = new ReadEditType("WRITE"); //$NON-NLS-1$
 
 	/**
 	 * copyModel is similar to a deep clone. The resulting model is shared,
@@ -137,54 +99,139 @@
 	 * unless the ReadEditType is NOTSHARED, in which case the resulting model
 	 * can not be saved.
 	 * 
-	 * @param oldId
-	 * @param newId
+	 * @param oldLocation
+	 * @param newLocation
+	 * @param type
 	 * @return
 	 * @throws ResourceInUse
 	 * 
-	 * 
 	 * ISSUE: is this important enough to be API, or can clients solve
-	 * themselves
+	 * themselves 
 	 */
 	IStructuredModel copyModel(IPath oldLocation, IPath newLocation, ReadEditType type) throws ResourceInUse;
 
 	/**
+	 * createNewInstance is similar to clone, except the new instance has no
+	 * text content. Note: this produces an UNSHARED model, for temporary use,
+	 * that has the same characteristics as original model. If a true shared
+	 * model is desired, use "copy".
+	 * 
+	 * ISSUE: still needed?
+	 * 
+	 * @param requester
+	 * @param model
+	 * @return
+	 * @throws IOException
+	 */
+	public IStructuredModel createNewInstance(Object requester, IStructuredModel model) throws IOException;
+
+	/**
 	 * Factory method, since a proper IStructuredDocument must have a proper
-	 * parser assigned. Note: its assume that IFile does not actually exist as
+	 * parser assigned. Note: its assume that IPath does not actually exist as
 	 * a resource yet. If it does, ResourceAlreadyExists exception is thrown.
 	 * If the resource does already exist, then createStructuredDocumentFor is
 	 * the right API to use.
 	 * 
 	 * ISSUE: do we want to support this via model manager, or else where?
 	 * ISSUE: do we need two of these? What's legacy use case?
+	 * 
+	 * @param location
+	 * @param progressMonitor
+	 * @return
+	 * @throws ResourceAlreadyExists
+	 * @throws IOException
+	 * @throws CoreException
 	 */
 	IStructuredDocument createNewStructuredDocumentFor(IPath location, IProgressMonitor progressMonitor) throws ResourceAlreadyExists, IOException, CoreException;
 
 	/**
 	 * Factory method, since a proper IStructuredDocument must have a proper
-	 * parser assigned. Note: clients should verify IFile exists before using
-	 * this method. If this IFile does not exist, then
-	 * createNewStructuredDocument is the correct API to use.
+	 * parser assigned. Note: clients should verify that the resource
+	 * identified by the IPath exists before using this method. If this IFile
+	 * does not exist, then createNewStructuredDocument is the correct API to
+	 * use.
 	 * 
 	 * ISSUE: do we want to support this via model manager, or else where?
 	 * ISSUE: do we need two of these? What's legacy use case?
+	 * 
+	 * @param location
+	 * @param progressMonitor
+	 * @return
+	 * @throws IOException
+	 * @throws CoreException
 	 */
 	IStructuredDocument createStructuredDocumentFor(IPath location, IProgressMonitor progressMonitor) throws IOException, CoreException;
 
 	/**
-	 * Note: users of this 'model' must still release it when finished.
-	 * Returns null if there's not a model corresponding to document.
+	 * Note: callers of this method must still release the model when
+	 * finished. Returns the model for this document if it already exists and
+	 * is being shared. Returns null if this is not the case. The ReadEditType
+	 * must be either WRITE or SHARED.
 	 * 
 	 * ISSUE: should we accept IDocument on parameter for future evolution,
 	 * and constrain to StructuredDocuments at runtime?
+	 * 
+	 * @param requester
+	 * @param type
+	 * @param document
+	 * @return
 	 */
 	IStructuredModel getExistingModel(Object requester, ReadEditType type, IDocument document);
 
 	/**
+	 * Callers of this method must still release the model when finished.
+	 * Returns the model for this location if it already exists and is being
+	 * shared. Returns null if this is not the case. The ReadEditType must be
+	 * either WRITE or SHARED.
+	 * 
+	 * @param requester
+	 * @param type
+	 * @param location
+	 * @return
+	 */
+	public IStructuredModel getExistingModel(Object requester, ReadEditType type, IPath location);
+
+	/**
+	 * Returns the model that has the specified document as its structured
+	 * document.
+	 * 
+	 * @param requester
+	 * @param type
+	 * @param progressMonitor
+	 * @param document
+	 * @return
+	 */
+	public IStructuredModel getModel(Object requester, ReadEditType type, IProgressMonitor progressMonitor, IDocument document);
+
+	/**
+	 * Returns the model based on the content at the specified location.
+	 * 
+	 * @param requester
+	 * @param type
+	 * @param progressMonitor
+	 * @param location
+	 * @return
+	 * @throws IOException
+	 * @throws CoreException
+	 */
+	public IStructuredModel getModel(Object requester, ReadEditType type, IProgressMonitor progressMonitor, IPath location) throws IOException, CoreException;
+
+	/**
 	 * This method will not create a new model if it already exists ... if
 	 * force is false. The idea is that a client should call this method once
 	 * with force set to false. If the exception is thrown, then prompt client
 	 * if they want to overwrite.
+	 * 
+	 * @param requester
+	 * @param location
+	 * @param force
+	 * @param type
+	 * @param progressMonitor
+	 * @return
+	 * @throws ResourceAlreadyExists
+	 * @throws ResourceInUse
+	 * @throws IOException
+	 * @throws CoreException
 	 */
 	IStructuredModel getNewModel(Object requester, IPath location, boolean force, ReadEditType type, IProgressMonitor progressMonitor) throws ResourceAlreadyExists, ResourceInUse, IOException, CoreException;
 
@@ -192,15 +239,19 @@
 	 * This function returns true if there are other references to the
 	 * underlying model.
 	 * 
-	 * @param id
-	 *            Object The id of the model
+	 * @param location
+	 * @return
 	 */
 	boolean isShared(IPath location);
 
 	/**
 	 * This function returns true if there are other references to the
-	 * underlying model, shared in the specified way.
+	 * underlying model, shared in the specified way. The ReadEditType must be
+	 * either WRITE or SHARED.
 	 * 
+	 * @param location
+	 * @param type
+	 * @return
 	 */
 	boolean isShared(IPath location, ReadEditType type);
 
@@ -209,11 +260,30 @@
 	 * assumed the contentType has already been changed, and this method uses
 	 * the text of the old one, to repopulate the text of the new one.
 	 * 
+	 * @param model
+	 * @return
+	 * @throws IOException
 	 */
 	IStructuredModel reinitialize(IStructuredModel model) throws IOException;
 
 
 	/**
+	 * This is used by clients to signify that they are finished with a model
+	 * and will no longer access it or any of its underlying data (such as its
+	 * structured document). The ReadEditType must match what ever the client
+	 * used in the corresponding 'get' method.
+	 * 
+	 * This method must be called for every 'get'. Clients should use the
+	 * try/finally pattern to ensure the release is called even if there is an
+	 * unexpected exception.
+	 * 
+	 * @param requester
+	 * @param structuredModel
+	 * @param type
+	 */
+	void releaseModel(Object requester, IStructuredModel structuredModel, ReadEditType type);
+
+	/**
 	 * Writes the underlying document to the IPath.
 	 * 
 	 * ISSUE: we want to just "dump" contents to location, but need to spec.
@@ -232,8 +302,8 @@
 	 * 
 	 * 
 	 * @param structuredModel
-	 * @param location
-	 *            normalized?
+	 * @param location - already normalized?
+	 * @param progressMonitor
 	 * @throws UnsupportedEncodingException
 	 * @throws IOException
 	 * @throws CoreException
@@ -249,7 +319,8 @@
 	 * or other client that might desire user intervention to save a resource.
 	 * 
 	 * @param structuredModel
-	 * @param location
+	 * @param location - already normalized?
+	 * @param progressMonitor
 	 * @throws UnsupportedEncodingException
 	 * @throws IOException
 	 * @throws CoreException
@@ -258,20 +329,4 @@
 	 * created with
 	 */
 	void saveModelIfNotShared(IStructuredModel structuredModel, IPath location, IProgressMonitor progressMonitor) throws UnsupportedEncodingException, IOException, CoreException;
-
-	/**
-	 * This is used by clients to signify that they are finished with a model
-	 * and will no longer access it or any of its underlying data (such as its
-	 * structured document). The ReadEditType must match what ever the client
-	 * used in the corresponding 'get' method.
-	 * 
-	 * This method must be called for every 'get'. Clients should use the
-	 * try/finally pattern to ensure the release is called even if there is an
-	 * unexpected exception.
-	 * 
-	 * @param structuredModel
-	 * @param type
-	 */
-	void releaseModel(Object requester, IStructuredModel structuredModel, ReadEditType type);
-
 }