java doc and internalization
diff --git a/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IndexedRegion.java b/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IndexedRegion.java
index a7373e8..e32dd65 100644
--- a/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IndexedRegion.java
+++ b/bundles/org.eclipse.wst.sse.core/src/org/eclipse/wst/sse/core/IndexedRegion.java
@@ -17,13 +17,20 @@
/**
* This type is used to indicate positions and lengths in source. Notice that
* while getEndOffset and getLength are redundant, given that
+ *
* <pre>
* <code>
- * getEndOffset() == getStartOffset() + getLength();
+ * getEndOffset() == getStartOffset() + getLength();
* </code>
- * </pre>
- * we provide (require) both since in some cases implementors may be
- * able to provide one or the other more efficiently.
+ * </pre>
+ *
+ * we provide (require) both since in some cases implementors may be able to
+ * provide one or the other more efficiently.
+ *
+ * Note: it is not part of the API contract that implementors of IndexedRegion --
+ * as a whole collection for a particular source -- must completely cover the
+ * original source. They currently often do, so thought I'd mention explicitly
+ * this may not always be true.
*
* @since 1.0
*/
diff --git a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMAttr.java b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMAttr.java
index 738a71c..6126c5e 100644
--- a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMAttr.java
+++ b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMAttr.java
@@ -31,6 +31,8 @@
* Get's the region in attribute representing the '=' sign. May or may not
* have whitespace surrounding it.
*
+ * @return ITextRegion - the region representing the equals sign, or null
+ * if their is no equals sign.
*/
ITextRegion getEqualRegion();
@@ -38,14 +40,15 @@
* Gets the source location of the end of the attribute name, including
* whitespace.
*
- * @return
+ * @return int - the source location of the end of the attribute name,
+ * including whitespace.
*/
int getNameRegionEndOffset();
/**
* Gets the source location of the start of the attribute name.
*
- * @return
+ * @return int - the source location of the start of the attribute name.
*/
int getNameRegionStartOffset();
@@ -53,7 +56,7 @@
/**
* Gets the text associated with the attribute name.
*
- * @return
+ * @return String - the text associated with the attribute name.
*/
String getNameRegionText();
@@ -61,28 +64,32 @@
* Gets the source location of the end of the attribute name, excluding
* whitespace.
*
- * @return
+ * @return int - returns the source location of the end of the attribute
+ * name, excluding whitespace.
*/
int getNameRegionTextEndOffset();
/**
* Gets the source location of the start of the attribute value.
*
- * @return
+ * @return int - returns the source location of the start of the attribute
+ * value.
+ *
+ * ISSUE: need to better spec interaction with quote marks
*/
int getValueRegionStartOffset();
/**
* Gets the text associated with the attribute value.
*
- * @return
+ * @return String - returns the text associated with the attribute value.
*/
String getValueRegionText();
/**
* Check if Attr has a nested value (such as a JSP expression).
*
- * @return true if contains a nested value
+ * @return true if contains a nested value, false otherwise.
*/
boolean hasNestedValue();
@@ -98,13 +105,19 @@
* false if attribute is preceeded by a prefix (whether valid name space
* or not). Returns true if its owning element is a global element.
*
+ * @return true if attribute is defined globally for document. Returns
+ * false if attribute is preceeded by a prefix (whether valid name
+ * space or not). Returns true if its owning element is a global
+ * element.
*/
boolean isGlobalAttr();
/**
* Returns true if is xml attr
*
- * ISSUE: need to figure out how to specify this one.
+ * ISSUE: need to figure out how to specify this one in a meaningful way.
+ *
+ * @return boolean - returns true if is xml attr
*/
boolean isXMLAttr();
diff --git a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMDocument.java b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMDocument.java
index 0ee6563..52b6eb1 100644
--- a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMDocument.java
+++ b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMDocument.java
@@ -23,7 +23,7 @@
/**
* This interface enables creation of DOCTYPE declaration and some DOM Level 2
- * interfaces.
+ * interfaces. May be referenced but not implemented by clients.
*
* @since 1.0
*/
@@ -40,43 +40,59 @@
* --%>)
* @return Element element instance
* @throws DOMException
- * throwed if the element name is registered as comment
- * element
+ * thrown if the element name is registered as comment element
*/
Element createCommentElement(String tagName, boolean isJSPTag) throws DOMException;
/**
* Creates a DocumentType node
+ *
+ * ISSUE: I believe this 'name' is the one specific in doctype extension,
+ * need to verify.
+ *
+ * @param name -
+ * name of the doctype
+ * @return DocumentType - returns a document type node.
*/
DocumentType createDoctype(String name);
/**
- * Returns the DocumnetType ID
+ * Returns the DocumentType ID. Unlike the standard DOM approach of
+ * "getDocumentType().getPublicId()", this method returns the id even if
+ * implicit.
*
+ * @return the DocumentType ID
*/
String getDocumentTypeId();
/**
- * isJSPDocument
+ * NOT API ... needs to be removed/changed
*
* ISSUE: need to specify
*
+ * @return true if is JSPDocument
+ * @deprecated
+ *
*/
boolean isJSPDocument();
/**
- * isJSPType
+ * NOT API ... needs to be removed/changed
*
* ISSUE: need to specify
*
+ * @deprecated
+ *
*/
boolean isJSPType();
/**
- * isXMLType
+ * NOT API ... needs to be removed/changed
*
* ISSUE: need to specify
*
+ * @deprecated
+ *
*/
boolean isXMLType();
diff --git a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMDocumentType.java b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMDocumentType.java
index c4c21c1..e11bf69 100644
--- a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMDocumentType.java
+++ b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMDocumentType.java
@@ -28,14 +28,16 @@
/**
* Sets document type's public id, as source.
*
- * @param publicId
+ * @param String -
+ * the publicId
*/
void setPublicId(String publicId);
/**
* Sets docment type's system id, as source.
*
- * @param systemId
+ * @param String -
+ * the systemId
*/
void setSystemId(String systemId);
}
diff --git a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMElement.java b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMElement.java
index 40b17b5..1d40e3d 100644
--- a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMElement.java
+++ b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMElement.java
@@ -26,57 +26,81 @@
public interface IDOMElement extends IDOMNode, Element {
/**
- * @deprecated this should probably not be public
+ * Retuns the start offset of the end tag.
+ *
+ * ISSUE: need to sort out need for this
+ *
+ * @return int - the start offset of the end tag.
*/
int getEndStartOffset();
/**
- * get's the end tag name
- */
- String getEndTagName();
-
- /**
- * @deprecated this should probably not be public
+ * Returns the end offset of the
*
+ * ISSUE: need to sort out need for this
+ *
+ * @return int - the end offset of the start tag.
*/
int getStartEndOffset();
/**
- * Returns true if has an end tag
+ * Returns true if has an end tag.
+ *
+ * In our source-oriented DOM, sometimes Elements are "ended", even
+ * without an explicit end tag in the source.
+ *
+ * @return true if has an end tag.
*/
boolean hasEndTag();
/**
* returns true if has a start tag.
+ *
+ * In our source-oriented DOM, a lone end tag will cause a node to be
+ * created in the tree, unlike well-formed-only DOMs.
+ *
+ * @return true if has a start tag.
*/
boolean hasStartTag();
/**
- * returns true if this element is a comment
+ * returns true if this element is a comment element
+ *
+ * @return true if this element is a comment element
*/
boolean isCommentTag();
/**
* isEmptyTag method
*
- * @return boolean
+ * @return boolean - true if is empty tag, false otherwise
*/
boolean isEmptyTag();
/**
+ * NOT CLIENT API
+ *
+ *
+ * @deprecated - I believe this can be cleaned out.
*/
boolean isEndTag();
/**
* Returns true for "global tag" (basically, without prefix)
+ *
+ * @return true for "global tag" (basically, without prefix)
*/
boolean isGlobalTag();
/**
- * Returns true for no the start and the end tags
+ * Returns true for no start and the end tags in source.
*
* Provided for some very special cases when, for example, and HTML tag is
- * assumed in an HTML document that does not have an HTML tag.
+ * assumed in an HTML document that does not have a literal HTML tag.
+ *
+ * ISSUE: check with clients to see if still needed
+ *
+ * @return true or no start and the end tags in source.
*/
boolean isImplicitTag();
@@ -92,32 +116,38 @@
/**
* Returns true if start tag is closed.
*
+ * @return true if start tag is closed.
*/
boolean isStartTagClosed();
/**
* returns true if is xml tag
*
- * ISSUE: I need to spec this better.
+ * ISSUE: need to spec this better.
*
+ * @return true if is xml tag
*/
boolean isXMLTag();
/**
+ * NOT CLIENT API
+ *
* notifyEndTagChanged
*
- * @deprecated this should probably not be public
*/
void notifyEndTagChanged();
/**
+ * NOT CLIENT API
+ *
* notifyStartTagChanged
*
- * @deprecated this should probably not be public
*/
void notifyStartTagChanged();
/**
+ * NOT CLIENT API
+ *
* Signify that this tag is a comment
*
* For use only by parsers.
@@ -126,6 +156,8 @@
void setCommentTag(boolean isCommentTag);
/**
+ * NOT CLIENT API
+ *
* Signify that this tag is an empty tag
*
* For use only by parsers
@@ -133,10 +165,15 @@
void setEmptyTag(boolean isEmptyTag);
/**
+ * NOT CLIENT API
+ *
* Signify that this tag is a JSP tag
*
* For use only by parsers
*
+ * ISSUE: I have had one non-parsing client who has had to use this ...
+ * need to check
+ *
*/
void setJSPTag(boolean isJSPTag);
}
diff --git a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMModel.java b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMModel.java
index ae07b79..2ad6f1f 100644
--- a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMModel.java
+++ b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMModel.java
@@ -38,6 +38,8 @@
ISourceGenerator getGenerator();
/**
+ * NOT CLIENT API
+ *
* Returns an XMLModelNotifier. Clients should not use.
*
* ISSUE: should be "internalized".
@@ -46,6 +48,8 @@
XMLModelNotifier getModelNotifier();
/**
+ * NOT CLIENT API
+ *
* Sets the model notifier Clients should not use.
*
* ISSUE: need to review with legacy clients.
diff --git a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMNode.java b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMNode.java
index bdfc0e1..e9f7a5d 100644
--- a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMNode.java
+++ b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMNode.java
@@ -23,8 +23,11 @@
import org.w3c.dom.Node;
/**
- * A interface to make concept clearer, just to denote the combination of
- * three other interfaces.
+ * This interface describes the extended functionality of our source-oriented
+ * DOM. First, our nodes extend the w3c Node interface, IndexedRegion, and
+ * INodeNotifier. Plus, has the extra methods called out here.
+ *
+ * ISSUE: the 'read-only' API should be broken out in their own interface
*
* @since 1.0
*
@@ -34,56 +37,106 @@
/**
* Gets the last structured document region of this node.
*
- * @return
+ * ISSUE: need to resolve getEnd/getLast confusion.
+ *
+ * @return IStructuredDocumentRegion - returns the last structured
+ * document region associated with
*/
IStructuredDocumentRegion getEndStructuredDocumentRegion();
/**
* Gets the first structured document region of this node.
*
- * @return
+ * ISSUE: need to resolve getFirst/getStart confusion
+ *
+ * @return the first structured document region of this node.
*/
IStructuredDocumentRegion getFirstStructuredDocumentRegion();
/**
* Gets the last structured document region of this node.
*
- * @return
+ * ISSUE: need to resolve getEnd/getLast confusion.
+ *
+ * @return IStructuredDocumentRegion - returns the last structured
+ * document region associated with
*/
IStructuredDocumentRegion getLastStructuredDocumentRegion();
/**
- * Returns the model associated with this node.
+ * Returns the model associated with this node. Returns null if not part
+ * of an active model.
+ *
+ * @return IDOMModel - returns the IDOMModel this node is part of.
*/
IDOMModel getModel();
/**
- * Returns a region representing the name of this node.
+ * Get's the region representing the name of this node
+ *
+ * ISSUE: only implemented/used at attribute and DTDNodes -- should move.
+ *
+ * @return ITextRegion - returns the ITextRegion associated with this
+ * Node.
+ *
+ * @deprecated
*/
ITextRegion getNameRegion();
/**
- * Returns the source representing this node.
+ * Returns the literal source representing this node in source document.
+ *
+ * ISSUE: need to fix implementation to match.
+ *
+ * @return the literal source representing this node in source document.
*/
String getSource();
/**
- * Returns the first StructuredDocumentRegion of this Node.
+ * Gets the first structured document region of this node.
+ *
+ * ISSUE: need to resolve getFirst/getStart confusion
+ *
+ * @return the first structured document region of this node.
*/
IStructuredDocumentRegion getStartStructuredDocumentRegion();
/**
- * Returns the structured Document that underlies this model.
+ * Returns the structured document that underlies this node's model.
+ *
+ * Returns null if this node is not actively part of a source document. In
+ * contrast, in the pure DOM world, "owning document" is not null even
+ * after a node is deleted from the DOM.
+ *
+ * ISSUE: we need to fix our implementation to match this spec.
+ *
+ * @return the structured document.
*/
IStructuredDocument getStructuredDocument();
/**
- * Get's the region representing the value of this node.
+ * Get's the region representing the value of this node if only one
+ * ITextRegion, null otherwise.
+ *
+ * ISSUE: only implemented/used at attribute level, move "down".
+ *
+ * @return ITextRegion - returns the ITextRegion associated with this
+ * Node.
+ *
+ * @deprecated
*/
ITextRegion getValueRegion();
/**
- * Get's the source of this nodes value.
+ * Returns a string representing the source of this node, but with
+ * character enties converted (e.g. < is converted to '<').
+ *
+ * ISSUE: need to better spec extent of this conversion, we may not know
+ * all character entities.
+ *
+ * ISSUE: need to fix implementation to match spec.
+ *
+ * @return String - get's the source of this Node.
*/
String getValueSource();
@@ -96,14 +149,19 @@
boolean isChildEditable();
/**
- * Returns true if tag is closed.
+ * Returns true if tag is closed in source.
+ *
+ * In our source orient DOM we sometimes end a Node without it being
+ * explicitly closed in source.
+ *
+ * @return boolean - true if node is closed
*/
boolean isClosed();
/**
- * Returns true if this node is a container.
+ * Returns true if this node can contain children.
*
- * @return boolean
+ * @return boolean - true if this node can contain children.
*/
boolean isContainer();
@@ -126,7 +184,7 @@
void setDataEditable(boolean editable);
/**
- * Set's readonly state of data
+ * Sets readonly state of data
*
* faster approach to set read-only state.
*/
diff --git a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMText.java b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMText.java
index c2e6a1d..8b463be 100644
--- a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMText.java
+++ b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/IDOMText.java
@@ -23,26 +23,35 @@
* @since 1.0
*
*/
-
public interface IDOMText extends IDOMNode, Text {
/**
+ * NOT API - can be eliminated or moved to ltk level
+ *
* Appends the content of the text node
+ *
+ * @param text -
+ * the Text to append.
*/
void appendText(Text text);
/**
- * Inserts the content of the text node at the specified position
- */
- void insertText(Text text, int offset);
-
- /**
+ * NOT API - can be eliminated or moved to ltk level
+ *
* Returns true if is not valid.
*/
boolean isInvalid();
/**
- * Returns true if is entirely white space
+ * Returns true if is entirely white space.
+ *
+ * This is intened to be better performing that all clients getting the
+ * source, and checking themselves.
+ *
+ * ISSUE: need to clarify if implementation is pure to "white space" as
+ * per DOM spec?
+ *
+ * @return true if is entirely white space.
*/
boolean isWhitespace();
}
diff --git a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/ISourceGenerator.java b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/ISourceGenerator.java
index 22842f7..6c31027 100644
--- a/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/ISourceGenerator.java
+++ b/bundles/org.eclipse.wst.xml.core/src/org/eclipse/wst/xml/core/document/ISourceGenerator.java
@@ -28,6 +28,8 @@
*
* ISourceGenerator allows DOM models to generate source appropriate for their
* parameter, relative to the model that provides the source generator.
+ *
+ * ISSUE: This should be part of "ltk" level.
*/
public interface ISourceGenerator {