raise javadoc awareness of LanguageSubstitutor (IDEA-CR-22159)

platform/core-api/src/com/intellij/lang/Language.java

@@ -36,7 +36,9 @@ import java.util.concurrent.ConcurrentMap;
  * and its register instance wrapped with {@link LanguageFileType} instance via {@code FileTypeManager.getInstance().registerFileType()}.
  * There should be exactly one instance of each Language.
  * It is usually created when creating {@link LanguageFileType} and can be retrieved later with {@link #findInstance(Class)}.
- * For the list of standard languages, see {@code com.intellij.lang.StdLanguages}.
+ * For the list of standard languages, see {@code com.intellij.lang.StdLanguages}.<p/>
+ *
+ * The language coming from file type can be changed by {@link com.intellij.psi.LanguageSubstitutor}
  */
 public abstract class Language extends UserDataHolderBase {
   private static final Logger LOG = Logger.getInstance("#com.intellij.lang.Language");

platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java

@@ -25,6 +25,7 @@ import java.nio.charset.Charset;
 
 /**
  * Kind of file types capable to provide {@link Language}.
+ * Note that the associated language can still be overridden by a {@link com.intellij.psi.LanguageSubstitutor}.
  */
 public abstract class LanguageFileType implements FileType{
   private final Language myLanguage;