Bug 83794 - API issue with logical structures

2 files changed, 23 insertions, 10 deletions

diff --git a/org.eclipse.debug.core/core/org/eclipse/debug/core/ILogicalStructureProvider.java b/org.eclipse.debug.core/core/org/eclipse/debug/core/ILogicalStructureProvider.java
index 2bd68f31e..93c57c5a0 100644
--- a/org.eclipse.debug.core/core/org/eclipse/debug/core/ILogicalStructureProvider.java
+++ b/org.eclipse.debug.core/core/org/eclipse/debug/core/ILogicalStructureProvider.java
@@ -16,7 +16,22 @@ import org.eclipse.debug.core.model.IValue;
  * Provides logical structure types applicable to a raw implementation value from
  * a debug model. Associated with a logical structure provider extension.
  * <p>
- * Clients contributing logical structure providers should implement this
+ * The following is an example of a logical structure provider extension:
+ * <pre>
+ *  <extension point="org.eclipse.debug.core.logicalStructureProviders">
+ *   <logicalStructureProvider
+ *    class="com.example.ExampleLogicalStructureProvider"
+ *    modelIdentifier="com.example.debug.model">
+ *   </logicalStructureProvider>
+ * </extension>
+ * </pre>
+ * </p>
+ * In the example above, the specified logical structure provider will be consulted for
+ * alternative logical structures for values from the <code>com.example.debug.model</code>
+ * debug model as they are displayed in the variables view.
+ * </p>
+ * <p>
+ * Clients contributing logical structure providers must implement this
  * interface.
  * </p>
  * @since 3.1
diff --git a/org.eclipse.debug.core/core/org/eclipse/debug/core/ILogicalStructureType.java b/org.eclipse.debug.core/core/org/eclipse/debug/core/ILogicalStructureType.java
index 653ef6b21..e4d09ebc7 100644
--- a/org.eclipse.debug.core/core/org/eclipse/debug/core/ILogicalStructureType.java
+++ b/org.eclipse.debug.core/core/org/eclipse/debug/core/ILogicalStructureType.java
@@ -44,18 +44,16 @@ import org.eclipse.debug.core.model.ILogicalStructureTypeDelegate2;
  * </ul>
  * </p>
  * <p>
- * 
- * TODO: review the doc for the new provider extension point
- * 
- * 
- * Clients are not intended to implement this interface. Instead clients
- * providing logical strucutre types provide and implement an
- * <code>ILogicalStructureTypeDelegate</code>. Clients may optionally implement
- * <code>ILogicalStructureTypeDelegate2</code> to provide dynamic descriptions
- * of logical structures.
+ * Clients contributing logicalStructureType extensions are not intended to implement
+ * this interface. Rather, they provide an <code>ILogicalStructureTypeDelegate</code>
+ * that optionally implements <code>ILogicalStructureTypeDelegate2</code> to provide
+ * dynamic descriptions of logical structures.
+ * Since 3.1, clients contributing logicalStructureProviders extensions may implement this
+ * interface to return a collection of logical structure types applicable to a value.
  * </p>
  * @since 3.0
  * @see org.eclipse.debug.core.model.ILogicalStructureTypeDelegate
+ * @see org.eclipse.debug.core.ILogicalStructureProvider
  */
 public interface ILogicalStructureType extends ILogicalStructureTypeDelegate, ILogicalStructureTypeDelegate2 {