Skip to main content
summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAndre Weinand2002-06-26 14:49:03 +0000
committerAndre Weinand2002-06-26 14:49:03 +0000
commit616540c64e9765559b0412072b7b2f50891db1e3 (patch)
tree048f0aa56a754dd7f99bfa5e75ae85aeae821460
parent354bbfa3a10225cd29c2222fd1601c2e7a78dc6c (diff)
downloadeclipse.platform.team-616540c64e9765559b0412072b7b2f50891db1e3.tar.gz
eclipse.platform.team-616540c64e9765559b0412072b7b2f50891db1e3.tar.xz
eclipse.platform.team-616540c64e9765559b0412072b7b2f50891db1e3.zip
Updated JavDoc package.html files
-rw-r--r--bundles/org.eclipse.compare/buildnotes_compare.html8
-rw-r--r--bundles/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html36
-rw-r--r--bundles/org.eclipse.compare/compare/org/eclipse/compare/package.html87
-rw-r--r--bundles/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html49
-rw-r--r--bundles/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html71
-rw-r--r--bundles/org.eclipse.compare/plugins/org.eclipse.compare/buildnotes_compare.html8
-rw-r--r--bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html36
-rw-r--r--bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/package.html87
-rw-r--r--bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html49
-rw-r--r--bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html71
10 files changed, 354 insertions, 148 deletions
diff --git a/bundles/org.eclipse.compare/buildnotes_compare.html b/bundles/org.eclipse.compare/buildnotes_compare.html
index ec37a0f1c..3ca3702e1 100644
--- a/bundles/org.eclipse.compare/buildnotes_compare.html
+++ b/bundles/org.eclipse.compare/buildnotes_compare.html
@@ -11,6 +11,14 @@
<h1>
Eclipse Platform Build Notes<br>
Compare</h1>
+Eclipse Build Input June 27th 2002
+
+<h2>
+What's new in this drop</h2>
+Updated JavaDoc package.html files
+
+<h1>
+<hr WIDTH="100%"></h1>
Eclipse Build Input June 25th 2002
<h2>
diff --git a/bundles/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html b/bundles/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html
index 28d91eedb..18e0a1bce 100644
--- a/bundles/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html
+++ b/bundles/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html
@@ -11,25 +11,35 @@ Support for compare and merge viewers which show the
content side-by-side.
<h2>
Package Specification</h2>
-The <tt>ContentMergeViewer</tt> is an abstract compare and merge viewer
+
+The <b>ContentMergeViewer</b> is an abstract compare and merge viewer
with two side-by-side content areas and an optional content area for a
common ancestor (for three-way compare). Because the implementation makes
no assumptions about the content type it is a subclass responsibility to
-deal with a specific type.
-<p>A <tt>ContentMergeViewer</tt> accesses its model by means of a content
-provider which must implement the
-<br><tt>IMergeViewerContentProvider</tt> interface.
-<p>The <tt>TextMergeViewer</tt> is the standard concrete subclass of <tt>ContentMergeViewer</tt>.
-A text merge viewer uses the <tt>RangeDifferencer</tt> to perform a textual,
-line-by-line comparison of two (or three) input documents. For text lines
-that differ the <tt>TextMergeViewer</tt> uses an <tt>ITokenComparator</tt>
-to find longest sequences of matching and non-matching tokens. The <tt>TextMergeViewer</tt>'s
+deal with a specific type. Its subclass <b>ImageMergeViewer</b> in
+package org.eclipse.compare.internal shows how to base a simple
+mergeviewer for images on <b>ContentMergeViewer</b>.
+<p>
+
+A <b>ContentMergeViewer</b> accesses its model by means of a content
+provider which must implement the <b>IMergeViewerContentProvider</b> interface.
+<p>
+
+The <b>TextMergeViewer</b> is the standard concrete subclass of
+<b>ContentMergeViewer</b> for comparing and merging text content.
+<br>
+A text merge viewer uses the <b>org.eclipse.compare.rangedifferencer.RangeDifferencer</b>
+to perform a textual, line-by-line comparison of two (or three) input documents.
+For text lines that differ the <b>TextMergeViewer</b> uses an <b>ITokenComparator</b>
+to find longest sequences of matching and non-matching tokens.
+The <b>TextMergeViewer</b>'s
default token compare works on characters separated by whitespace. If a
different strategy is needed (for example, Java tokens in a Java-aware
merge viewer), clients can create their own token comparators by implementing
-the <tt>ITokenComparator</tt> interface.
-<p>The <tt>TextMergeViewer</tt> not only works on whole documents but on
+the <b>ITokenComparator</b> interface.
+<p>The <b>TextMergeViewer</b> not only works on whole documents but on
subranges of documents too. In this case the viewer's input must be an
-<tt>IDocumentRange</tt> instead of an <tt>IDocument</tt>.
+<b>IDocumentRange</b> instead of an <b>IDocument</b>.
+
</body>
</html>
diff --git a/bundles/org.eclipse.compare/compare/org/eclipse/compare/package.html b/bundles/org.eclipse.compare/compare/org/eclipse/compare/package.html
index fb0ad6215..409b1ebd9 100644
--- a/bundles/org.eclipse.compare/compare/org/eclipse/compare/package.html
+++ b/bundles/org.eclipse.compare/compare/org/eclipse/compare/package.html
@@ -11,40 +11,89 @@ Provides support for performing structural and textual
compare operations on arbitrary data and displaying the results.
<h2>
Package Specification</h2>
-The class <tt>CompareUI</tt> defines the entry point to initiate a configurable
+
+The class <b>CompareUI</b> defines the entry point to initiate a configurable
compare operation on arbitrary resources. The result of the compare is
opened into a compare editor where the details can be browsed and edited
in dynamically selected structure and content viewers.
-<p>A compare operation must be implemented as a subclass of <tt>CompareEditorInput</tt>.
-A <tt>CompareEditorInput</tt> runs a (potentially lengthy) compare operation
+<p>
+
+A compare operation must be implemented as a subclass of <b>CompareEditorInput</b>.
+A <b>CompareEditorInput</b> runs a (potentially lengthy) compare operation
under progress monitor control, creates a UI for drilling-down into the
compare results, tracks the dirty state of the result in case of merge,
and saves any changes that occured during a merge.
-<p>An instance of <tt>CompareConfiguration</tt> configures various UI aspects
+<p>
+
+The <b>NavigationAction</b> is used to navigate (step) through the individual
+differences of a <b>CompareEditorInput</b>.
+<p>
+
+An instance of <b>CompareConfiguration</b> configures various UI aspects
of compare/merge viewers like title labels and images, or whether a side
-of a merge viewer is editable. It is passed to the <tt>CompareEditorInput</tt>
+of a merge viewer is editable. It is passed to the <b>CompareEditorInput</b>
on creation.
-<p>When implementing a compare operation clients have to provide a tree
-of <tt>IStructureComparator</tt> (see package org.eclipse.compare.structuremergeviewer)
-and <tt>IStreamContentAccessor</tt> that can be passed as the input to
-the differencing engine (org.eclipse.compare.structuremergeviewer.Differencer).
-A <tt>ResourceNode</tt> is a convenience class that implements both interfaces
-for Eclipse workbench resources (org.eclipse.core.resources.IResource).
+<p>
+
+When implementing a hierarchical compare operation as a subclass of
+<b>CompareEditorInput</b> clients have to provide a tree of objects where each
+node implements the interface
+<b>org.eclipse.compare.structuremergeviewer.IStructureComparator</b>.
+This interface is used by the hierarchical differencing engine
+(<b>org.eclipse.compare.structuremergeviewer.Differencer</b>) to walk the tree.
+<br>
+In addition every leaf of the tree must implement the <b>IStreamContentAccessor</b>
+interface in order to give the differencing engine access to its stream content.
+<p>
+
+The abstract class <b>BufferedContent</b> provides a default implementation
+for the <b>IStreamContentAccessor</b> and <b>IContentChangeNotifier</b> interfaces.
+Its subclass <b>ResourceNode</b> adds an implementation for the
+<b>IStructureComparator</b> and <b>ITypedElement</b> interfaces
+based on Eclipse workbench resources (org.eclipse.core.resources.IResource).
It can be used without modification as the input to the differencing engine.
-<p>The <tt>EditionSelectionDialog</tt> is a simple selection dialog where
+<p>
+
+The <b>ZipFileStructureCreator</b> is an implementation of the
+<b>org.eclipse.compare.structuremergeviewer.IStructureCreator</b> interface
+and makes the contents of a zip archive available as a
+hierarchical structure of <b>IStructureComparator</b>s which can be easily compared
+by the differencing engine (<b>org.eclipse.compare.structuremergeviewer.Differencer</b>).
+It is a good example for how to make structured files available to the hierarchical
+compare functionality of the Compare plugin.
+<p>
+
+The <b>EditionSelectionDialog</b> is a simple selection dialog where
one input element can be compared against a list of historic variants (<i>editions</i>)
of the same input element. The dialog can be used to implement functions
-like <i>"Replace with Version"</i> or
-<br><i>"Replace with Edition"</i> on workbench resources.
-<p>In addition it is possible to specify a subsection of the input element
+like <i>"Replace with Version"</i> or <i>"Replace with Edition"</i> on workbench resources.
+<p>
+
+In addition it is possible to specify a subsection of the input element
(e.g. a method in a Java source file) by means of a <i>path</i>. In this
case the dialog compares only the subsection (as specified by the path)
with the corresponding subsection in the list of editions. This functionality
can be used to implement <i>"Replace with Method Edition"</i> for the Java
language.
-<p>The <tt>EditionSelectionDialog</tt> requires that the editions implement
-the <tt>IStreamContentAccessor</tt> and <tt>IModificationDate</tt> interfaces.
-The <tt>HistoryItem</tt> is a convenience class that implements these interfaces
-for <tt>IFileState</tt> objects.
+<p>
+
+The <b>EditionSelectionDialog</b> requires that the editions implement
+the <b>IStreamContentAccessor</b> and <b>IModificationDate</b> interfaces.
+The <b>HistoryItem</b> is a convenience class that implements these interfaces
+for <b>IFileState</b> objects.
+<p>
+
+
+The <b>CompareViewerPane</b> is a convenience class which provides
+a label and local toolbar for a compare viewer (or any other subclass of a
+JFace <b>Viewer</b>).
+<br>
+Its abstract subclass <b>CompareViewerSwitchingPane</b> supports <i>dynamic
+viewer switching</i>, that is the viewer installed in the pane is dynamically
+determined by the pane's input object.
+Both classes are useful if you want to use compare viewers outside the context of
+a compare editor, for example in a dialog or wizard.
+
+
</body>
</html>
diff --git a/bundles/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html b/bundles/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html
index 2e4ffaf2b..0a7413ca1 100644
--- a/bundles/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html
+++ b/bundles/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html
@@ -11,27 +11,34 @@ Provides support for finding the differences between
two or three sequences of comparable entities.
<h2>
Package Specification</h2>
-The class <tt>Differencer</tt> finds longest sequences of matching and
-non-matching comparable entities.
-<p>Clients must supply the input to the differencer as an implementation
-of the <tt>IRangeComparator</tt> interface.
-<br>An <tt>IRangeComparator</tt> breaks the input data into a sequence
+
+The class <b>RangeDifferencer</b> finds longest sequences of matching and
+non-matching comparable entities. Its implementation is based on
+an objectified version of the algorithm described in:
+<i>A File Comparison Program,</i> by Webb Miller and Eugene W. Myers,
+Software Practice and Experience, Vol. 15, Nov. 1985.
+<p>
+
+Clients must supply the input to the differencer as an implementation
+of the <b>IRangeComparator</b> interface.
+An <b>IRangeComparator</b> breaks the input data into a sequence
of entities and provides a method for comparing
-<br>one entity with the entity in another <tt>IRangeComparator</tt>.
-<br>For example, to compare two text documents and find longest common
-sequences
-<br>of matching and non-matching lines, the implementation of <tt>IRangeComparator
-</tt>must break the document
-<br>into lines and provide a method for testing whether two lines are considered
-equal.
-<p>The differencer returns the differences among these sequences as an
-array of <tt>RangeDifference</tt> objects.
-<br>Every single <tt>RangeDifference</tt> describes kind of difference
-(no change, change, addition, deletion)
-<br>and the corresponding ranges of the underlying comparable entities
-in the two or three inputs.
-<p>The algorithm used is an objectified version of one described in:
-<br><i>A File Comparison Program,</i> by Webb Miller and Eugene W. Myers,
-<br>Software Practice and Experience, Vol. 15, Nov. 1985.
+one entity with the entity in another <b>IRangeComparator</b>.
+<p>
+
+For example, to compare two text documents and find longest common
+sequences of matching and non-matching lines,
+the implementation of <b>IRangeComparator</b>
+must break the document into lines and provide a method for testing
+whether two lines are considered equal.
+See <b>org.eclipse.compare.internal.DocLineComparator</b> for how this can be done.
+<p>
+
+The differencer returns the differences among these sequences as an
+array of <b>RangeDifference</b> objects.
+Every single <b>RangeDifference</b> describes the kind of difference
+(no change, change, addition, deletion) and the corresponding ranges
+of the underlying comparable entities in the two or three inputs.
+
</body>
</html>
diff --git a/bundles/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html b/bundles/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html
index b0cc1b33d..c45a167bc 100644
--- a/bundles/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html
+++ b/bundles/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html
@@ -11,40 +11,69 @@ Provides support for finding and displaying the differences
between hierarchically structured data.
<h2>
Package Specification</h2>
-The class <tt>Differencer</tt> is a differencing engine for hierarchically
+
+The class <b>Differencer</b> is a differencing engine for hierarchically
structured data. It takes two or three inputs and performs a two-way or
three-way compare on them.
-<p>If the input elements to the differencing engine implement the <tt>IStructureComparator</tt>
-interface the engine recursively applies itself&nbsp; to the children of
-the input element. Leaf elements must implement the <tt>IStreamContentAccessor</tt>
-interface (see package <tt>org.eclipse.compare</tt>) so that the
-differencer can perform a bytewise comparison on them.
-<p>By default the differencing engine returns the result of the compare
-as a tree of <tt>DiffNode</tt> objects. Every <tt>DiffNode</tt> describes
-the changes among the two or three inputs.
-<p>A tree of <tt>DiffNodes</tt> can be displayed in a <tt>DiffTreeViewer</tt>.
-The <tt>DiffTreeViewer</tt> requires that inner nodes of the tree implement
-the <tt>IDiffContainer</tt> interface and leafs the <tt>IDiffElement</tt>
-interface.
-<p>The typical steps to compare hierarchically structured data and to display
+<p>
+
+If the input elements to the differencing engine implement the <b>IStructureComparator</b>
+interface the engine recursively applies itself to the children of
+the input element. Leaf elements must implement the <b>org.eclipse.compare.IStreamContentAccessor</b>
+interface so that the differencer can perform a bytewise comparison on their contents.
+<p>
+
+One good example for this is <b>org.eclipse.compare.ResourceNode</b> which implements both interfaces
+(and more) for Eclipse workspace resources (org.eclipse.core.resources.IResource).
+<p>
+
+Another example is the <b>DocumentRangeNode</b> which can be used to compare hierarchical structures
+that are superimposed on a document, that is where nodes and leafs correspond to ranges in a document
+(<b>org.eclipse.compare.contentmergeviewer.IDocumentRange</b>).
+<br>
+Typically <b>DocumentRangeNode</b>s are created while parsing a document and they represent
+the semantic entities of the document (e.g. a Java class, method or field).
+The two subclasses <b>JavaNode</b> (in org.eclipse.jdt.internal.ui.compare)
+and <b>PropertyNode</b> (in org.eclipse.jdt.internal.ui.compare) are good examples for this.
+<p>
+
+By default the differencing engine returns the result of the compare operation
+as a tree of <b>DiffNode</b> objects. However, this can be changed by overriding
+a single method of the engine.
+<p>
+
+Every <b>DiffNode</b> describes the changes among the two or three inputs.
+<p>
+
+A tree of <b>DiffNodes</b> can be displayed in a <b>DiffTreeViewer</b>.
+The <b>DiffTreeViewer</b> requires that inner nodes of the tree implement
+the <b>IDiffContainer</b> interface and leafs the <b>IDiffElement</b> interface.
+<p>
+
+The typical steps to compare hierarchically structured data and to display
the differences would be to:
<ul>
<li>
-map the input data into a tree of <tt>IStructureComparator</tt> and <tt>IStreamContentAccessor</tt>s,</li>
+map the input data into a tree of <b>IStructureComparator</b> and <b>IStreamContentAccessor</b>s,</li>
<li>
-perform the compare operation by means of the <tt>Differencer</tt>, and</li>
+perform the compare operation by means of the <b>Differencer</b>, and</li>
<li>
-feed the differencing result into the <tt>DiffTreeViewer</tt>.</li>
+feed the differencing result into the <b>DiffTreeViewer</b>.</li>
</ul>
-The <tt>StructureDiffViewer</tt> is a specialized <tt>DiffTreeViewer</tt>
+
+The <b>StructureDiffViewer</b> is a specialized <b>DiffTreeViewer</b>
that automates the three steps from above. It takes a single input object
-of type <tt>ICompareInput</tt> from which it retrieves the two or three
-input elements to compare. Then it uses a <tt>IStructureCreator</tt> to
-extract a tree of <tt>IStructureComparator</tt> and <tt>IStreamContentAccessor</tt>
+of type <b>ICompareInput</b> from which it retrieves the two or three
+input elements to compare. Then it uses a <b>IStructureCreator</b> to
+extract a tree of <b>IStructureComparator</b> and <b>IStreamContentAccessor</b>
from them. These trees are then compared with the differencing engine and
the result is displayed in the tree viewer.
+<p>
+
+
+
</body>
</html>
diff --git a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/buildnotes_compare.html b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/buildnotes_compare.html
index ec37a0f1c..3ca3702e1 100644
--- a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/buildnotes_compare.html
+++ b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/buildnotes_compare.html
@@ -11,6 +11,14 @@
<h1>
Eclipse Platform Build Notes<br>
Compare</h1>
+Eclipse Build Input June 27th 2002
+
+<h2>
+What's new in this drop</h2>
+Updated JavaDoc package.html files
+
+<h1>
+<hr WIDTH="100%"></h1>
Eclipse Build Input June 25th 2002
<h2>
diff --git a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html
index 28d91eedb..18e0a1bce 100644
--- a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html
+++ b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/contentmergeviewer/package.html
@@ -11,25 +11,35 @@ Support for compare and merge viewers which show the
content side-by-side.
<h2>
Package Specification</h2>
-The <tt>ContentMergeViewer</tt> is an abstract compare and merge viewer
+
+The <b>ContentMergeViewer</b> is an abstract compare and merge viewer
with two side-by-side content areas and an optional content area for a
common ancestor (for three-way compare). Because the implementation makes
no assumptions about the content type it is a subclass responsibility to
-deal with a specific type.
-<p>A <tt>ContentMergeViewer</tt> accesses its model by means of a content
-provider which must implement the
-<br><tt>IMergeViewerContentProvider</tt> interface.
-<p>The <tt>TextMergeViewer</tt> is the standard concrete subclass of <tt>ContentMergeViewer</tt>.
-A text merge viewer uses the <tt>RangeDifferencer</tt> to perform a textual,
-line-by-line comparison of two (or three) input documents. For text lines
-that differ the <tt>TextMergeViewer</tt> uses an <tt>ITokenComparator</tt>
-to find longest sequences of matching and non-matching tokens. The <tt>TextMergeViewer</tt>'s
+deal with a specific type. Its subclass <b>ImageMergeViewer</b> in
+package org.eclipse.compare.internal shows how to base a simple
+mergeviewer for images on <b>ContentMergeViewer</b>.
+<p>
+
+A <b>ContentMergeViewer</b> accesses its model by means of a content
+provider which must implement the <b>IMergeViewerContentProvider</b> interface.
+<p>
+
+The <b>TextMergeViewer</b> is the standard concrete subclass of
+<b>ContentMergeViewer</b> for comparing and merging text content.
+<br>
+A text merge viewer uses the <b>org.eclipse.compare.rangedifferencer.RangeDifferencer</b>
+to perform a textual, line-by-line comparison of two (or three) input documents.
+For text lines that differ the <b>TextMergeViewer</b> uses an <b>ITokenComparator</b>
+to find longest sequences of matching and non-matching tokens.
+The <b>TextMergeViewer</b>'s
default token compare works on characters separated by whitespace. If a
different strategy is needed (for example, Java tokens in a Java-aware
merge viewer), clients can create their own token comparators by implementing
-the <tt>ITokenComparator</tt> interface.
-<p>The <tt>TextMergeViewer</tt> not only works on whole documents but on
+the <b>ITokenComparator</b> interface.
+<p>The <b>TextMergeViewer</b> not only works on whole documents but on
subranges of documents too. In this case the viewer's input must be an
-<tt>IDocumentRange</tt> instead of an <tt>IDocument</tt>.
+<b>IDocumentRange</b> instead of an <b>IDocument</b>.
+
</body>
</html>
diff --git a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/package.html b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/package.html
index fb0ad6215..409b1ebd9 100644
--- a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/package.html
+++ b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/package.html
@@ -11,40 +11,89 @@ Provides support for performing structural and textual
compare operations on arbitrary data and displaying the results.
<h2>
Package Specification</h2>
-The class <tt>CompareUI</tt> defines the entry point to initiate a configurable
+
+The class <b>CompareUI</b> defines the entry point to initiate a configurable
compare operation on arbitrary resources. The result of the compare is
opened into a compare editor where the details can be browsed and edited
in dynamically selected structure and content viewers.
-<p>A compare operation must be implemented as a subclass of <tt>CompareEditorInput</tt>.
-A <tt>CompareEditorInput</tt> runs a (potentially lengthy) compare operation
+<p>
+
+A compare operation must be implemented as a subclass of <b>CompareEditorInput</b>.
+A <b>CompareEditorInput</b> runs a (potentially lengthy) compare operation
under progress monitor control, creates a UI for drilling-down into the
compare results, tracks the dirty state of the result in case of merge,
and saves any changes that occured during a merge.
-<p>An instance of <tt>CompareConfiguration</tt> configures various UI aspects
+<p>
+
+The <b>NavigationAction</b> is used to navigate (step) through the individual
+differences of a <b>CompareEditorInput</b>.
+<p>
+
+An instance of <b>CompareConfiguration</b> configures various UI aspects
of compare/merge viewers like title labels and images, or whether a side
-of a merge viewer is editable. It is passed to the <tt>CompareEditorInput</tt>
+of a merge viewer is editable. It is passed to the <b>CompareEditorInput</b>
on creation.
-<p>When implementing a compare operation clients have to provide a tree
-of <tt>IStructureComparator</tt> (see package org.eclipse.compare.structuremergeviewer)
-and <tt>IStreamContentAccessor</tt> that can be passed as the input to
-the differencing engine (org.eclipse.compare.structuremergeviewer.Differencer).
-A <tt>ResourceNode</tt> is a convenience class that implements both interfaces
-for Eclipse workbench resources (org.eclipse.core.resources.IResource).
+<p>
+
+When implementing a hierarchical compare operation as a subclass of
+<b>CompareEditorInput</b> clients have to provide a tree of objects where each
+node implements the interface
+<b>org.eclipse.compare.structuremergeviewer.IStructureComparator</b>.
+This interface is used by the hierarchical differencing engine
+(<b>org.eclipse.compare.structuremergeviewer.Differencer</b>) to walk the tree.
+<br>
+In addition every leaf of the tree must implement the <b>IStreamContentAccessor</b>
+interface in order to give the differencing engine access to its stream content.
+<p>
+
+The abstract class <b>BufferedContent</b> provides a default implementation
+for the <b>IStreamContentAccessor</b> and <b>IContentChangeNotifier</b> interfaces.
+Its subclass <b>ResourceNode</b> adds an implementation for the
+<b>IStructureComparator</b> and <b>ITypedElement</b> interfaces
+based on Eclipse workbench resources (org.eclipse.core.resources.IResource).
It can be used without modification as the input to the differencing engine.
-<p>The <tt>EditionSelectionDialog</tt> is a simple selection dialog where
+<p>
+
+The <b>ZipFileStructureCreator</b> is an implementation of the
+<b>org.eclipse.compare.structuremergeviewer.IStructureCreator</b> interface
+and makes the contents of a zip archive available as a
+hierarchical structure of <b>IStructureComparator</b>s which can be easily compared
+by the differencing engine (<b>org.eclipse.compare.structuremergeviewer.Differencer</b>).
+It is a good example for how to make structured files available to the hierarchical
+compare functionality of the Compare plugin.
+<p>
+
+The <b>EditionSelectionDialog</b> is a simple selection dialog where
one input element can be compared against a list of historic variants (<i>editions</i>)
of the same input element. The dialog can be used to implement functions
-like <i>"Replace with Version"</i> or
-<br><i>"Replace with Edition"</i> on workbench resources.
-<p>In addition it is possible to specify a subsection of the input element
+like <i>"Replace with Version"</i> or <i>"Replace with Edition"</i> on workbench resources.
+<p>
+
+In addition it is possible to specify a subsection of the input element
(e.g. a method in a Java source file) by means of a <i>path</i>. In this
case the dialog compares only the subsection (as specified by the path)
with the corresponding subsection in the list of editions. This functionality
can be used to implement <i>"Replace with Method Edition"</i> for the Java
language.
-<p>The <tt>EditionSelectionDialog</tt> requires that the editions implement
-the <tt>IStreamContentAccessor</tt> and <tt>IModificationDate</tt> interfaces.
-The <tt>HistoryItem</tt> is a convenience class that implements these interfaces
-for <tt>IFileState</tt> objects.
+<p>
+
+The <b>EditionSelectionDialog</b> requires that the editions implement
+the <b>IStreamContentAccessor</b> and <b>IModificationDate</b> interfaces.
+The <b>HistoryItem</b> is a convenience class that implements these interfaces
+for <b>IFileState</b> objects.
+<p>
+
+
+The <b>CompareViewerPane</b> is a convenience class which provides
+a label and local toolbar for a compare viewer (or any other subclass of a
+JFace <b>Viewer</b>).
+<br>
+Its abstract subclass <b>CompareViewerSwitchingPane</b> supports <i>dynamic
+viewer switching</i>, that is the viewer installed in the pane is dynamically
+determined by the pane's input object.
+Both classes are useful if you want to use compare viewers outside the context of
+a compare editor, for example in a dialog or wizard.
+
+
</body>
</html>
diff --git a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html
index 2e4ffaf2b..0a7413ca1 100644
--- a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html
+++ b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/rangedifferencer/package.html
@@ -11,27 +11,34 @@ Provides support for finding the differences between
two or three sequences of comparable entities.
<h2>
Package Specification</h2>
-The class <tt>Differencer</tt> finds longest sequences of matching and
-non-matching comparable entities.
-<p>Clients must supply the input to the differencer as an implementation
-of the <tt>IRangeComparator</tt> interface.
-<br>An <tt>IRangeComparator</tt> breaks the input data into a sequence
+
+The class <b>RangeDifferencer</b> finds longest sequences of matching and
+non-matching comparable entities. Its implementation is based on
+an objectified version of the algorithm described in:
+<i>A File Comparison Program,</i> by Webb Miller and Eugene W. Myers,
+Software Practice and Experience, Vol. 15, Nov. 1985.
+<p>
+
+Clients must supply the input to the differencer as an implementation
+of the <b>IRangeComparator</b> interface.
+An <b>IRangeComparator</b> breaks the input data into a sequence
of entities and provides a method for comparing
-<br>one entity with the entity in another <tt>IRangeComparator</tt>.
-<br>For example, to compare two text documents and find longest common
-sequences
-<br>of matching and non-matching lines, the implementation of <tt>IRangeComparator
-</tt>must break the document
-<br>into lines and provide a method for testing whether two lines are considered
-equal.
-<p>The differencer returns the differences among these sequences as an
-array of <tt>RangeDifference</tt> objects.
-<br>Every single <tt>RangeDifference</tt> describes kind of difference
-(no change, change, addition, deletion)
-<br>and the corresponding ranges of the underlying comparable entities
-in the two or three inputs.
-<p>The algorithm used is an objectified version of one described in:
-<br><i>A File Comparison Program,</i> by Webb Miller and Eugene W. Myers,
-<br>Software Practice and Experience, Vol. 15, Nov. 1985.
+one entity with the entity in another <b>IRangeComparator</b>.
+<p>
+
+For example, to compare two text documents and find longest common
+sequences of matching and non-matching lines,
+the implementation of <b>IRangeComparator</b>
+must break the document into lines and provide a method for testing
+whether two lines are considered equal.
+See <b>org.eclipse.compare.internal.DocLineComparator</b> for how this can be done.
+<p>
+
+The differencer returns the differences among these sequences as an
+array of <b>RangeDifference</b> objects.
+Every single <b>RangeDifference</b> describes the kind of difference
+(no change, change, addition, deletion) and the corresponding ranges
+of the underlying comparable entities in the two or three inputs.
+
</body>
</html>
diff --git a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html
index b0cc1b33d..c45a167bc 100644
--- a/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html
+++ b/bundles/org.eclipse.compare/plugins/org.eclipse.compare/compare/org/eclipse/compare/structuremergeviewer/package.html
@@ -11,40 +11,69 @@ Provides support for finding and displaying the differences
between hierarchically structured data.
<h2>
Package Specification</h2>
-The class <tt>Differencer</tt> is a differencing engine for hierarchically
+
+The class <b>Differencer</b> is a differencing engine for hierarchically
structured data. It takes two or three inputs and performs a two-way or
three-way compare on them.
-<p>If the input elements to the differencing engine implement the <tt>IStructureComparator</tt>
-interface the engine recursively applies itself&nbsp; to the children of
-the input element. Leaf elements must implement the <tt>IStreamContentAccessor</tt>
-interface (see package <tt>org.eclipse.compare</tt>) so that the
-differencer can perform a bytewise comparison on them.
-<p>By default the differencing engine returns the result of the compare
-as a tree of <tt>DiffNode</tt> objects. Every <tt>DiffNode</tt> describes
-the changes among the two or three inputs.
-<p>A tree of <tt>DiffNodes</tt> can be displayed in a <tt>DiffTreeViewer</tt>.
-The <tt>DiffTreeViewer</tt> requires that inner nodes of the tree implement
-the <tt>IDiffContainer</tt> interface and leafs the <tt>IDiffElement</tt>
-interface.
-<p>The typical steps to compare hierarchically structured data and to display
+<p>
+
+If the input elements to the differencing engine implement the <b>IStructureComparator</b>
+interface the engine recursively applies itself to the children of
+the input element. Leaf elements must implement the <b>org.eclipse.compare.IStreamContentAccessor</b>
+interface so that the differencer can perform a bytewise comparison on their contents.
+<p>
+
+One good example for this is <b>org.eclipse.compare.ResourceNode</b> which implements both interfaces
+(and more) for Eclipse workspace resources (org.eclipse.core.resources.IResource).
+<p>
+
+Another example is the <b>DocumentRangeNode</b> which can be used to compare hierarchical structures
+that are superimposed on a document, that is where nodes and leafs correspond to ranges in a document
+(<b>org.eclipse.compare.contentmergeviewer.IDocumentRange</b>).
+<br>
+Typically <b>DocumentRangeNode</b>s are created while parsing a document and they represent
+the semantic entities of the document (e.g. a Java class, method or field).
+The two subclasses <b>JavaNode</b> (in org.eclipse.jdt.internal.ui.compare)
+and <b>PropertyNode</b> (in org.eclipse.jdt.internal.ui.compare) are good examples for this.
+<p>
+
+By default the differencing engine returns the result of the compare operation
+as a tree of <b>DiffNode</b> objects. However, this can be changed by overriding
+a single method of the engine.
+<p>
+
+Every <b>DiffNode</b> describes the changes among the two or three inputs.
+<p>
+
+A tree of <b>DiffNodes</b> can be displayed in a <b>DiffTreeViewer</b>.
+The <b>DiffTreeViewer</b> requires that inner nodes of the tree implement
+the <b>IDiffContainer</b> interface and leafs the <b>IDiffElement</b> interface.
+<p>
+
+The typical steps to compare hierarchically structured data and to display
the differences would be to:
<ul>
<li>
-map the input data into a tree of <tt>IStructureComparator</tt> and <tt>IStreamContentAccessor</tt>s,</li>
+map the input data into a tree of <b>IStructureComparator</b> and <b>IStreamContentAccessor</b>s,</li>
<li>
-perform the compare operation by means of the <tt>Differencer</tt>, and</li>
+perform the compare operation by means of the <b>Differencer</b>, and</li>
<li>
-feed the differencing result into the <tt>DiffTreeViewer</tt>.</li>
+feed the differencing result into the <b>DiffTreeViewer</b>.</li>
</ul>
-The <tt>StructureDiffViewer</tt> is a specialized <tt>DiffTreeViewer</tt>
+
+The <b>StructureDiffViewer</b> is a specialized <b>DiffTreeViewer</b>
that automates the three steps from above. It takes a single input object
-of type <tt>ICompareInput</tt> from which it retrieves the two or three
-input elements to compare. Then it uses a <tt>IStructureCreator</tt> to
-extract a tree of <tt>IStructureComparator</tt> and <tt>IStreamContentAccessor</tt>
+of type <b>ICompareInput</b> from which it retrieves the two or three
+input elements to compare. Then it uses a <b>IStructureCreator</b> to
+extract a tree of <b>IStructureComparator</b> and <b>IStreamContentAccessor</b>
from them. These trees are then compared with the differencing engine and
the result is displayed in the tree viewer.
+<p>
+
+
+
</body>
</html>

Back to the top