Author: ihab.awad
Date: Sun Jul 12 21:55:25 2009
New Revision: 3567
Modified:
trunk/src/com/google/caja/lexer/ExternalReference.java
trunk/src/com/google/caja/plugin/PluginEnvironment.java
Log:
Clarifies documentation of PluginEnvironment and ExternalReference.
Modified: trunk/src/com/google/caja/lexer/ExternalReference.java
==============================================================================
--- trunk/src/com/google/caja/lexer/ExternalReference.java (original)
+++ trunk/src/com/google/caja/lexer/ExternalReference.java Sun Jul 12
21:55:25 2009
@@ -17,10 +17,31 @@
/**
* A reference to an external resource from an input.
- * <p>
- * In {...@code <script src="foo.js"/>} the URI foo.js is an external
reference,
- * and the reference position is the position of the text {code "foo.js"}.
- *
+ *
+ * <p>For example, parsing a file {...@code x/y/foo.html} with contents:
+ *
+ * <pre>
+ * <script src="../z/bar.js"/>
+ * </pre>
+ *
+ * will result in an {...@code ExternalReference} with:
+ *
+ * <ul>
+ *
+ * <li>A {...@link #getReferencePosition() reference position} which is the
span
+ * in {...@code foo.html} where the reference occurred. This position
contains,
+ * among other things, the URI {...@code "x/y/foo.html"}.</li>
+ *
+ * <li>The target {...@link #getUri() URI}, {...@code "../z/bar.js"}.
+ *
+ * </ul>
+ *
+ * <p>Note that, in the case of HTML links (as in the above example), the
+ * URI is implicitly relative to the reference position; in other words,
the
+ * author of {...@code x/y/foo.html} meant to retrieve a script at
+ * {...@code "x/z/bar.js"}. The {...@code ExternalReference} itself, however,
is
+ * oblivious to this level of interpretation.
+ *
* @author [email protected] (Mike Samuel)
*/
public final class ExternalReference {
Modified: trunk/src/com/google/caja/plugin/PluginEnvironment.java
==============================================================================
--- trunk/src/com/google/caja/plugin/PluginEnvironment.java (original)
+++ trunk/src/com/google/caja/plugin/PluginEnvironment.java Sun Jul 12
21:55:25 2009
@@ -18,24 +18,23 @@
import com.google.caja.lexer.ExternalReference;
/**
- * Specifies how the plugin resolves external resources such as scripts and
- * stylesheets.
+ * Specifies how the cajoler resolves external resources such as scripts
and
+ * stylesheets in the code being cajoled.
*
* @author [email protected]
*/
public interface PluginEnvironment {
/**
- * Loads an externally resource such as the src of a script tags or
- * a stylesheet.
+ * Loads an external resource such as the {...@code src} of a {...@code
script}
+ * tag or a stylesheet.
*
- * @return null if it could not be loaded.
+ * @return null if the resource could not be loaded.
*/
CharProducer loadExternalResource(ExternalReference ref, String
mimeType);
/**
- * May be overridden to apply a URI policy and return a URI that
enforces that
- * policy.
+ * Applies a URI policy and returns a URI that enforces that policy.
*
* @return null if the URI cannot be made safe.
*/
