From 913a6e5d5304d50745ec4bb6c67bb50dc853ac00 Mon Sep 17 00:00:00 2001
From: nik <Nikolay.Chashnikov@jetbrains.com>
Date: Tue, 2 Dec 2014 14:25:26 +0300
Subject: [PATCH] javadoc for PsiLanguageInjectionHost

---
 .../src/com/intellij/psi/LiteralTextEscaper.java   | 14 ++++++++++++++
 .../com/intellij/psi/PsiLanguageInjectionHost.java | 13 +++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/platform/core-api/src/com/intellij/psi/LiteralTextEscaper.java b/platform/core-api/src/com/intellij/psi/LiteralTextEscaper.java
index bc93b01f0c78..f992e6c43f23 100644
--- a/platform/core-api/src/com/intellij/psi/LiteralTextEscaper.java
+++ b/platform/core-api/src/com/intellij/psi/LiteralTextEscaper.java
@@ -29,9 +29,17 @@ public abstract class LiteralTextEscaper<T extends PsiLanguageInjectionHost> {
     myHost = host;
   }
 
+  /**
+   * Add decoded and unescaped characters from the host element to {@code outChars} buffer. If it's impossible to properly decode some chars
+   * from the specified range (e.g. if the range starts or ends inside escaped sequence), decode the longest acceptable prefix of the range and return {@code false}
+   * @param rangeInsideHost range to be decoded. It's guarantied to be inside {@link #getRelevantTextRange()}
+   * @param outChars buffer for output chars. Use {@code append} methods only, <strong>it's forbidden to modify or remove existing characters</strong>
+   * @return {@code true} if whole range was successfully decoded, {@code false} otherwise
+   */
   public abstract boolean decode(@NotNull TextRange rangeInsideHost, @NotNull StringBuilder outChars);
 
   /**
+   * This method is called only after {@link #decode}, so it's possible to prepare necessary data in {@link #decode} and then use it here.
    * @param offsetInDecoded offset in the parsed injected file
    * @param rangeInsideHost range where injection is performed,
    *   E.g. if some language fragment xyz was injected into string literal expression "xyz", then rangeInsideHost = (1,4)
@@ -53,11 +61,17 @@ public abstract class LiteralTextEscaper<T extends PsiLanguageInjectionHost> {
    */
   public abstract int getOffsetInHost(int offsetInDecoded, @NotNull TextRange rangeInsideHost);
 
+  /**
+   * @return range inside the host where injection can be performed; usually it's range of text without boundary quotes
+   */
   @NotNull
   public TextRange getRelevantTextRange() {
     return TextRange.from(0, myHost.getTextLength());
   }
 
+  /**
+   * @return {@code true} if the host cannot accept multiline content, {@code false} otherwise
+   */
   public abstract boolean isOneLine();
 
   public static <T extends PsiLanguageInjectionHost> LiteralTextEscaper<T> createSimple(T element) {
diff --git a/platform/core-api/src/com/intellij/psi/PsiLanguageInjectionHost.java b/platform/core-api/src/com/intellij/psi/PsiLanguageInjectionHost.java
index c1e015ec46ac..bc447903aa84 100644
--- a/platform/core-api/src/com/intellij/psi/PsiLanguageInjectionHost.java
+++ b/platform/core-api/src/com/intellij/psi/PsiLanguageInjectionHost.java
@@ -38,10 +38,23 @@ import java.util.List;
  * For all returned injected PSI elements, {@link InjectedLanguageManager#getInjectionHost(PsiElement)} returns PsiLanguageInjectionHost they were injected into.
  */
 public interface PsiLanguageInjectionHost extends PsiElement {
+  /**
+   * @return {@code true} if this instance can accept injections, {@code false} otherwise
+   */
   boolean isValidHost();
 
+  /**
+   * Update the host element using the provided text of the injected file. It may be required to escape characters from {@code text}
+   * in accordance with the host language syntax. The implementation may delegate to {@link com.intellij.psi.ElementManipulators#handleContentChange(PsiElement, String)}
+   * if {@link com.intellij.psi.ElementManipulator} implementation is registered for this element class
+   * @param text text of the injected file
+   * @return the updated instance
+   */
   PsiLanguageInjectionHost updateText(@NotNull String text);
 
+  /**
+   * @return {@link LiteralTextEscaper} instance which will be used to convert the content of this host element to the content of injected file
+   */
   @NotNull
   LiteralTextEscaper<? extends PsiLanguageInjectionHost> createLiteralTextEscaper();