From 76e5657a99cd6dc17295c5d8e83d7c207d4db6d1 Mon Sep 17 00:00:00 2001
From: Yan Zhulanow <yan.zhulanow@jetbrains.com>
Date: Wed, 13 Apr 2016 18:05:02 +0300
Subject: [PATCH] Minor: add Javadoc for UastContext/UastLanguagePlugin

---
 .../src/org/jetbrains/uast/UastContext.kt     | 16 ++++++
 .../org/jetbrains/uast/UastLanguagePlugin.kt  | 52 +++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/plugins/uast-common/src/org/jetbrains/uast/UastContext.kt b/plugins/uast-common/src/org/jetbrains/uast/UastContext.kt
index e84032d8af2..e4de99f8683 100644
--- a/plugins/uast-common/src/org/jetbrains/uast/UastContext.kt
+++ b/plugins/uast-common/src/org/jetbrains/uast/UastContext.kt
@@ -15,9 +15,25 @@
  */
 package org.jetbrains.uast
 
+/**
+ * Interface for the Uast context.
+ *
+ * Context is needed for resolution, cause the reference can point to the element of the different language.
+ */
 interface UastContext {
+    /**
+     * Returns all active language plugins.
+     */
     val languagePlugins: List<UastLanguagePlugin>
 
+    /**
+     * Convert an element of some language-specific AST to Uast element.
+     * If two or more language plugins can convert the given [element] type,
+     *  the first converter in the [languagePlugins] list will be chosen.
+     *
+     * @param element the language-specific AST element
+     * @return [UElement] instance, or null if [element] type is not supported by any of the provided language plugins.
+     */
     fun convert(element: Any?): UElement? {
         if (element == null) {
             return null
diff --git a/plugins/uast-common/src/org/jetbrains/uast/UastLanguagePlugin.kt b/plugins/uast-common/src/org/jetbrains/uast/UastLanguagePlugin.kt
index cab926584d5..bc937d35807 100644
--- a/plugins/uast-common/src/org/jetbrains/uast/UastLanguagePlugin.kt
+++ b/plugins/uast-common/src/org/jetbrains/uast/UastLanguagePlugin.kt
@@ -17,19 +17,71 @@ package org.jetbrains.uast
 
 import org.jetbrains.uast.visitor.UastVisitor
 
+/**
+ * Interface for the Uast element converter.
+ * Each [UastLanguagePlugin] should implement a proper [UastContext],
+ *  which translates language-specific AST elements to Uast elements.
+ */
 interface UastConverter {
+    /**
+     * Convert a language-specific AST element to the [UElement] implementation with the given parent.
+     *
+     * @param element the element of the supported language-specific AST.
+     * @param parent the parent of the newly created [UElement].
+     * @return a [UElement], or null if the given [element] is not supported by this converter.
+     *
+     * No exceptions should be thrown during conversion, return `null` instead.
+     */
     fun convert(element: Any?, parent: UElement): UElement?
+
+    /**
+     * Convert [element] to the [UElement] with the given parent.
+     */
     fun convertWithParent(element: Any?): UElement?
 
+    /**
+     * Checks if the file with the given [name] is supported.
+     *
+     * @param name the source file name.
+     * @return true, if the file is supported by this converter, false otherwise.
+     */
     fun isFileSupported(name: String): Boolean
 }
 
+/**
+ * Interface for the Uast language plugin.
+ *
+ * [UElement] implementations are loaded using language plugins provided in [UastContext].
+ * Each plugin must have a language-specific AST -> Uast (e.g. PsiElement -> UElement) converter.
+ */
 interface UastLanguagePlugin {
+    /**
+     * Returns converter for the specific language AST.
+     */
     val converter: UastConverter
+
+    /**
+     * Returns list of visitor extensions for the specific language AST.
+     */
     val visitorExtensions: List<UastVisitorExtension>
 }
 
+/**
+ * Interface for the Uast visitor extension.
+ *
+ * A language plugin could provide a number of visitor extensions, which transforms some [UElement] into another.
+ * For example, Java accessors (getters/setters) are expressed in Kotlin as properties,
+ *  but it can be useful to see them as functions in diagnostics, so the visitor extension
+ *  can convert such property accessor calls to the ordinary function calls.
+ */
 interface UastVisitorExtension {
+    /**
+     * Invoke extension on an element.
+     *
+     * @param element a [UElement] to process.
+     * @param visitor current visitor.
+     * @param context current context.
+     */
     operator fun invoke(element: UElement, visitor: UastVisitor, context: UastContext)
 }