diff --git a/platform/core-api/src/com/intellij/lang/injection/MultiHostRegistrar.java b/platform/core-api/src/com/intellij/lang/injection/MultiHostRegistrar.java
index 1c1859a489c1..76a6e343633c 100644
--- a/platform/core-api/src/com/intellij/lang/injection/MultiHostRegistrar.java
+++ b/platform/core-api/src/com/intellij/lang/injection/MultiHostRegistrar.java
@@ -23,16 +23,73 @@ import com.intellij.lang.Language;
import com.intellij.psi.PsiLanguageInjectionHost;
import com.intellij.openapi.util.TextRange;
+/**
+ * Provides ability to inject languages inside other PSI elements.
+ * E.g. inject SQL inside XML tag text or inject RegExp into Java string literals.
+ * These injected fragments are treated by IDE as separate tiny files in a specific language and corresponding code insight features,
+ * like completion, highlighting, navigation become available there.
+ * You can get hold of an instance of {@link MultiHostRegistrar} by registering your own implementation of {@link MultiHostInjector} and
+ * implementing its {@link MultiHostInjector#getLanguagesToInject(MultiHostRegistrar, com.intellij.psi.PsiElement)} method.
+ */
public interface MultiHostRegistrar {
- @NotNull /*this*/ MultiHostRegistrar startInjecting(@NotNull Language language);
+ /**
+ * Start injecting the {@code language} in this place.
+ * After you call {@link #startInjecting(Language)} you will have to call
+ * {@link #addPlace(String, String, PsiLanguageInjectionHost, TextRange)} one or several times
+ * and then call {@link #doneInjecting()}.
+ * After that the text in ranges (denoted by one or several {@link #addPlace(String, String, PsiLanguageInjectionHost, TextRange)} calls)
+ * will be treated by IDE as a code in the {@code language}.
+ * For example, in this Java fragment
+ * {@code String x = ""+""; }
+ * if you call
+ * - {@code startInjecting(XMLLanguage.getInstance());}
+ * - {@code addPlace(null, null, literal1, insideRange1);}
+ * - {@code addPlace(null, null, literal2, insideRange2);}
+ * - {@code doneInjecting();}
+ * You will have XML language injected in these string literals, along with its completion, navigation etc niceties.
+ * @return this
+ */
+ @NotNull /*this*/
+ MultiHostRegistrar startInjecting(@NotNull Language language);
/**
- * @param extension The injected file name will have this extension. Some parsers require extension. By default the extension is taken from the host file.
+ * The variant of {@link #startInjecting(Language)} with explicitly specified file extension.
+ * @param extension the created injected file name will have. Some parsers require specific extension. By default the extension is taken from the host file.
*/
@NotNull
- default /*this*/ MultiHostRegistrar startInjecting(@NotNull Language language, @Nullable String extension) {
+ default /*this*/
+ MultiHostRegistrar startInjecting(@NotNull Language language, @Nullable String extension) {
return startInjecting(language);
}
- @NotNull /*this*/ MultiHostRegistrar addPlace(@NonNls @Nullable String prefix, @NonNls @Nullable String suffix, @NotNull PsiLanguageInjectionHost host, @NotNull TextRange rangeInsideHost);
+
+ /**
+ * Specifies the range in the host file to be considered as injected file part.
+ * @see #startInjecting(Language) for the required workflow.
+ * @param prefix this part will be appended before.
+ * For example. to treat the following Java string literal as a HTML inner text:
+ * {@code String html = "Hello world";}
+ * You can call {@code addPlace("", "", literal, insideRange); }
+ *
+ * @param suffix this part will be appended after.
+ *
+ * @param host the text range of which the language will be injected into.
+ *
+ * @param rangeInsideHost into which the language will be injected.
+ * For example, to inject something inside Java string literal {@code String s = "xyz";}
+ * you will have to call {@code addPlace(prefix, suffix, literal, new TextRange(1, 4));} to inject inside double quotes.
+ * Injected file document text will be of length = 3 and equals to 'xyz'.
+ * If, however, you called {@code addPlace(prefix, suffix, literal, new TextRange(0, 5));} instead,
+ * the injected file text would consist of five characters '"', 'x', 'y', 'z', '"'.
+ */
+ @NotNull /*this*/
+ MultiHostRegistrar addPlace(@NonNls @Nullable String prefix, @NonNls @Nullable String suffix, @NotNull PsiLanguageInjectionHost host, @NotNull TextRange rangeInsideHost);
+
+
+ /**
+ * The final part of the injecting process.
+ * You have to call this method to tell the IDE you finished constructing the injection.
+ * @see #startInjecting(Language) for a required workflow.
+ */
void doneInjecting();
+
}
\ No newline at end of file