javadocs for ISourceElementParser/ISourceElementRequestor
diff --git a/core/plugins/org.eclipse.dltk.core/compiler/org/eclipse/dltk/compiler/ISourceElementRequestor.java b/core/plugins/org.eclipse.dltk.core/compiler/org/eclipse/dltk/compiler/ISourceElementRequestor.java
index 0e51852..9e8d870 100644
--- a/core/plugins/org.eclipse.dltk.core/compiler/org/eclipse/dltk/compiler/ISourceElementRequestor.java
+++ b/core/plugins/org.eclipse.dltk.core/compiler/org/eclipse/dltk/compiler/ISourceElementRequestor.java
@@ -9,6 +9,47 @@
  *******************************************************************************/
 package org.eclipse.dltk.compiler;
 
+import org.eclipse.dltk.core.ISourceElementParser;
+
+/**
+ * Part of the {@link ISourceElementParser} responsible for building the output.
+ * It gets notified of structural information as they are detected, relying on
+ * the requestor to assemble them together, based on the notifications it got.
+ * 
+ * <p>
+ * The structural investigation includes:
+ * </p>
+ * <ul>
+ * <li>package statement
+ * <li>import statements
+ * <li>types
+ * <li>fields
+ * <li>methods
+ * </ul>
+ * 
+ * <p>
+ * If reference information is requested, then all source constructs are
+ * investigated and type, field & method references are provided as well.
+ * </p>
+ * 
+ * <p>
+ * Any (parsing) problem encountered is also provided.
+ * </p>
+ * 
+ * <p>
+ * All positions are relative to the exact source fed to the parser.
+ * </p>
+ * 
+ * <p>
+ * Elements which are complex are notified in two steps:
+ * <li><code>enterElement</code> : once the element header has been identified
+ * <li><code>exitElement</code> : once the element has been fully consumed
+ * 
+ * <p>
+ * other simpler elements (package, import) are read all at once: -
+ * <code>acceptElement</code>.
+ * </p>
+ */
 public interface ISourceElementRequestor extends IElementRequestor {
 	/**
 	 * Adds selected field only if it isn't already added. If field is added
diff --git a/core/plugins/org.eclipse.dltk.core/model/org/eclipse/dltk/core/ISourceElementParser.java b/core/plugins/org.eclipse.dltk.core/model/org/eclipse/dltk/core/ISourceElementParser.java
index 068a3cb..63fc01d 100644
--- a/core/plugins/org.eclipse.dltk.core/model/org/eclipse/dltk/core/ISourceElementParser.java
+++ b/core/plugins/org.eclipse.dltk.core/model/org/eclipse/dltk/core/ISourceElementParser.java
@@ -12,6 +12,37 @@
 import org.eclipse.dltk.compiler.env.IModuleSource;
 import org.eclipse.dltk.compiler.problem.IProblemReporter;
 
+/**
+ * A source element parser extracts structural and reference information from a
+ * piece of source.
+ * 
+ * <p>
+ * The structural investigation includes:
+ * </p>
+ * <ul>
+ * <li>the package statement
+ * <li>import statements
+ * <li>types
+ * <li>fields
+ * <li>methods
+ * </ul>
+ * 
+ * <p>
+ * If reference information is requested, then all source constructs are
+ * investigated and type, field & method references are provided as well.
+ * </p>
+ * 
+ * <p>
+ * Any (parsing) problem encountered is also provided.
+ * </p>
+ * 
+ * <p>
+ * Language specific implementation is contributed via
+ * <code>org.eclipse.dltk.core.sourceElementParsers</code>.
+ * </p>
+ * 
+ * @see ISourceElementRequestor
+ */
 public interface ISourceElementParser {
 	/**
 	 * Parses contents of the module and report all information to the