path: root/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt

package org.jetbrains.dokka

import com.google.inject.Inject
import com.intellij.openapi.util.text.StringUtil
import com.intellij.psi.*
import com.intellij.psi.impl.JavaConstantExpressionEvaluator
import com.intellij.psi.impl.source.PsiClassReferenceType
import com.intellij.psi.util.InheritanceUtil
import com.intellij.psi.util.PsiTreeUtil
import org.jetbrains.kotlin.asJava.elements.KtLightDeclaration
import org.jetbrains.kotlin.asJava.elements.KtLightElement
import org.jetbrains.kotlin.kdoc.parser.KDocKnownTag
import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
import org.jetbrains.kotlin.lexer.KtTokens
import org.jetbrains.kotlin.psi.KtDeclaration
import org.jetbrains.kotlin.psi.KtModifierListOwner
import java.io.File

fun getSignature(element: PsiElement?) = when(element) {
    is PsiPackage -> element.qualifiedName
    is PsiClass -> element.qualifiedName
    is PsiField -> element.containingClass!!.qualifiedName + "$" + element.name
    is PsiMethod ->
        element.containingClass?.qualifiedName + "$" + element.name + "(" +
                element.parameterList.parameters.map { it.type.typeSignature() }.joinToString(",") + ")"
    else -> null
}

private fun PsiType.typeSignature(): String = when(this) {
    is PsiArrayType -> "Array((${componentType.typeSignature()}))"
    is PsiPrimitiveType -> "kotlin." + canonicalText.capitalize()
    is PsiClassType -> resolve()?.qualifiedName ?: className
    else -> mapTypeName(this)
}

private fun mapTypeName(psiType: PsiType): String = when (psiType) {
    is PsiPrimitiveType -> psiType.canonicalText
    is PsiClassType -> psiType.resolve()?.name ?: psiType.className
    is PsiEllipsisType -> mapTypeName(psiType.componentType)
    is PsiArrayType -> "kotlin.Array"
    else -> psiType.canonicalText
}

interface JavaDocumentationBuilder {
    fun appendFile(file: PsiJavaFile, module: DocumentationModule, packageContent: Map<String, Content>)
}

class JavaPsiDocumentationBuilder : JavaDocumentationBuilder {
    private val options: DocumentationOptions
    private val refGraph: NodeReferenceGraph
    private val docParser: JavaDocumentationParser
    private val externalDocumentationLinkResolver: ExternalDocumentationLinkResolver

    @Inject constructor(
            options: DocumentationOptions,
            refGraph: NodeReferenceGraph,
            logger: DokkaLogger,
            signatureProvider: ElementSignatureProvider,
            externalDocumentationLinkResolver: ExternalDocumentationLinkResolver
    ) {
        this.options = options
        this.refGraph = refGraph
        this.docParser = JavadocParser(refGraph, logger, signatureProvider, externalDocumentationLinkResolver)
        this.externalDocumentationLinkResolver = externalDocumentationLinkResolver
    }

    constructor(
        options: DocumentationOptions,
        refGraph: NodeReferenceGraph,
        docParser: JavaDocumentationParser,
        externalDocumentationLinkResolver: ExternalDocumentationLinkResolver
    ) {
        this.options = options
        this.refGraph = refGraph
        this.docParser = docParser
        this.externalDocumentationLinkResolver = externalDocumentationLinkResolver
    }

    override fun appendFile(file: PsiJavaFile, module: DocumentationModule, packageContent: Map<String, Content>) {
        if (skipFile(file) || file.classes.all { skipElement(it) }) {
            return
        }
        val packageNode = findOrCreatePackageNode(module, file.packageName, emptyMap(), refGraph)
        appendClasses(packageNode, file.classes)
    }

    fun appendClasses(packageNode: DocumentationNode, classes: Array<PsiClass>) {
        packageNode.appendChildren(classes) { build() }
    }

    fun register(element: PsiElement, node: DocumentationNode) {
        val signature = getSignature(element)
        if (signature != null) {
            refGraph.register(signature, node)
        }
    }

    fun link(node: DocumentationNode, element: PsiElement?) {
        val qualifiedName = getSignature(element)
        if (qualifiedName != null) {
            refGraph.link(node, qualifiedName, RefKind.Link)
        }
    }

    fun link(element: PsiElement?, node: DocumentationNode, kind: RefKind) {
        val qualifiedName = getSignature(element)
        if (qualifiedName != null) {
            refGraph.link(qualifiedName, node, kind)
        }
    }

    fun nodeForElement(element: PsiNamedElement,
                       kind: NodeKind,
                       name: String = element.name ?: "<anonymous>"): DocumentationNode {
        val (docComment, deprecatedContent, attrs, apiLevel, sdkExtSince, deprecatedLevel, artifactId, attribute) = docParser.parseDocumentation(element)
        val node = DocumentationNode(name, docComment, kind)
        if (element is PsiModifierListOwner) {
            node.appendModifiers(element)
            val modifierList = element.modifierList
            if (modifierList != null) {
                modifierList.annotations.filter { !ignoreAnnotation(it) }.forEach {
                    val annotation = it.build()
                    if (it.qualifiedName == "java.lang.Deprecated" || it.qualifiedName == "kotlin.Deprecated") {
                        node.append(annotation, RefKind.Deprecation)
                        annotation.convertDeprecationDetailsToChildren()
                    } else {
                        node.append(annotation, RefKind.Annotation)
                    }
                }
            }
        }
        if (deprecatedContent != null) {
            val deprecationNode = DocumentationNode("", deprecatedContent, NodeKind.Modifier)
            node.append(deprecationNode, RefKind.Deprecation)
        }
        if (element is PsiDocCommentOwner && element.isDeprecated && node.deprecation == null) {
            val deprecationNode = DocumentationNode("", Content.of(ContentText("Deprecated")), NodeKind.Modifier)
            node.append(deprecationNode, RefKind.Deprecation)
        }
        apiLevel?.let {
            node.append(it, RefKind.Detail)
        }
        sdkExtSince?.let {
            node.append(it, RefKind.Detail)
        }
        deprecatedLevel?.let {
            node.append(it, RefKind.Detail)
        }
        artifactId?.let {
            node.append(it, RefKind.Detail)
        }
        attrs.forEach {
            refGraph.link(node, it, RefKind.Detail)
            refGraph.link(it, node, RefKind.Owner)
        }
        attribute?.let {
            val attrName = node.qualifiedName()
            refGraph.register("Attr:$attrName", attribute)
        }
        return node
    }

    fun ignoreAnnotation(annotation: PsiAnnotation) = when(annotation.qualifiedName) {
        "java.lang.SuppressWarnings" -> true
        else -> false
    }

    fun <T : Any> DocumentationNode.appendChildren(elements: Array<T>,
                                                   kind: RefKind = RefKind.Member,
                                                   buildFn: T.() -> DocumentationNode) {
        elements.forEach {
            if (!skipElement(it)) {
                append(it.buildFn(), kind)
            }
        }
    }

    private fun skipFile(javaFile: PsiJavaFile): Boolean = options.effectivePackageOptions(javaFile.packageName).suppress

    private fun skipElement(element: Any) =
            skipElementByVisibility(element) ||
                    hasSuppressDocTag(element) ||
                    hasHideAnnotation(element) ||
                    skipElementBySuppressedFiles(element)

    private fun skipElementByVisibility(element: Any): Boolean =
        element is PsiModifierListOwner &&
                element !is PsiParameter &&
                !(options.effectivePackageOptions((element.containingFile as? PsiJavaFile)?.packageName ?: "").includeNonPublic) &&
                (element.hasModifierProperty(PsiModifier.PRIVATE) ||
                        element.hasModifierProperty(PsiModifier.PACKAGE_LOCAL) ||
                        element.isInternal())

    private fun skipElementBySuppressedFiles(element: Any): Boolean =
            element is PsiElement && element.containingFile.virtualFile != null && File(element.containingFile.virtualFile.path).absoluteFile in options.suppressedFiles

    private fun PsiElement.isInternal(): Boolean {
        val ktElement = (this as? KtLightElement<*, *>)?.kotlinOrigin ?: return false
        return (ktElement as? KtModifierListOwner)?.hasModifier(KtTokens.INTERNAL_KEYWORD) ?: false
    }

    fun <T : Any> DocumentationNode.appendMembers(elements: Array<T>, buildFn: T.() -> DocumentationNode) =
            appendChildren(elements, RefKind.Member, buildFn)

    fun <T : Any> DocumentationNode.appendDetails(elements: Array<T>, buildFn: T.() -> DocumentationNode) =
            appendChildren(elements, RefKind.Detail, buildFn)

    fun PsiClass.build(): DocumentationNode {
        val kind = when {
            isInterface -> NodeKind.Interface
            isEnum -> NodeKind.Enum
            isAnnotationType -> NodeKind.AnnotationClass
            isException() -> NodeKind.Exception
            else -> NodeKind.Class
        }
        val node = nodeForElement(this, kind)
        superTypes.filter { !ignoreSupertype(it) }.forEach { superType ->
            node.appendType(superType, NodeKind.Supertype)
            val superClass = superType.resolve()
            if (superClass != null) {
                link(superClass, node, RefKind.Inheritor)
            }
        }

        var methodsAndConstructors = methods

        if (constructors.isEmpty()) {
            // Having no constructor represents a class that only has an implicit/default constructor
            // so we create one synthetically for documentation
            val factory = JavaPsiFacade.getElementFactory(this.project)
            methodsAndConstructors += factory.createMethodFromText("public $name() {}", this)
        }
        node.appendDetails(typeParameters) { build() }
        node.appendMembers(methodsAndConstructors) { build() }
        node.appendMembers(fields) { build() }
        node.appendMembers(innerClasses) { build() }
        register(this, node)
        return node
    }

    fun PsiClass.isException() = InheritanceUtil.isInheritor(this, "java.lang.Throwable")

    fun ignoreSupertype(psiType: PsiClassType): Boolean = false
//            psiType.isClass("java.lang.Enum") || psiType.isClass("java.lang.Object")

    fun PsiClassType.isClass(qName: String): Boolean {
        val shortName = qName.substringAfterLast('.')
        if (className == shortName) {
            val psiClass = resolve()
            return psiClass?.qualifiedName == qName
        }
        return false
    }

    fun PsiField.build(): DocumentationNode {
        val node = nodeForElement(this, nodeKind())
        node.appendType(type)

        node.appendConstantValueIfAny(this)
        register(this, node)
        return node
    }

    private fun DocumentationNode.appendConstantValueIfAny(field: PsiField) {
        val modifierList = field.modifierList ?: return
        val initializer = field.initializer ?: return
        if (modifierList.hasExplicitModifier(PsiModifier.FINAL) &&
            modifierList.hasExplicitModifier(PsiModifier.STATIC)) {
            val value = JavaConstantExpressionEvaluator.computeConstantExpression(initializer, false) ?: return
            val text = when(value) {
                is String -> "\"${StringUtil.escapeStringCharacters(value)}\""
                else -> value.toString()
            }
            append(DocumentationNode(text, Content.Empty, NodeKind.Value), RefKind.Detail)
        }
    }

    private fun PsiField.nodeKind(): NodeKind = when {
        this is PsiEnumConstant -> NodeKind.EnumItem
        else -> NodeKind.Field
    }

    fun PsiMethod.build(): DocumentationNode {
        val node = nodeForElement(this, nodeKind(), name)

        if (!isConstructor) {
            node.appendType(returnType)
        }
        node.appendDetails(parameterList.parameters) { build() }
        node.appendDetails(typeParameters) { build() }
        register(this, node)
        return node
    }

    private fun PsiMethod.nodeKind(): NodeKind = when {
        isConstructor -> NodeKind.Constructor
        else -> NodeKind.Function
    }

    fun PsiParameter.build(): DocumentationNode {
        val node = nodeForElement(this, NodeKind.Parameter)
        node.appendType(type)
        if (type is PsiEllipsisType) {
            node.appendTextNode("vararg", NodeKind.Modifier, RefKind.Detail)
        }
        return node
    }

    fun PsiTypeParameter.build(): DocumentationNode {
        val node = nodeForElement(this, NodeKind.TypeParameter)
        extendsListTypes.forEach { node.appendType(it, NodeKind.UpperBound) }
        implementsListTypes.forEach { node.appendType(it, NodeKind.UpperBound) }
        return node
    }

    fun DocumentationNode.appendModifiers(element: PsiModifierListOwner) {
        val modifierList = element.modifierList ?: return

        PsiModifier.MODIFIERS.forEach {
            if (modifierList.hasExplicitModifier(it)) {
                appendTextNode(it, NodeKind.Modifier)
            }
        }
    }

    fun DocumentationNode.appendType(psiType: PsiType?, kind: NodeKind = NodeKind.Type) {
        if (psiType == null) {
            return
        }

        val node = psiType.build(kind)
        append(node, RefKind.Detail)

        // Attempt to create an external link if the psiType is one
        if (psiType is PsiClassReferenceType) {
            val target = psiType.reference.resolve()
            if (target != null) {
                val externalLink = externalDocumentationLinkResolver.buildExternalDocumentationLink(target)
                if (externalLink != null) {
                    node.append(DocumentationNode(externalLink, Content.Empty, NodeKind.ExternalLink), RefKind.Link)
                }
            }
        }
    }

    fun PsiType.build(kind: NodeKind = NodeKind.Type): DocumentationNode {
        val name = mapTypeName(this)
        val node = DocumentationNode(name, Content.Empty, kind)
        if (this is PsiClassType) {
            node.appendDetails(parameters) { build(NodeKind.Type) }
            link(node, resolve())
        }
        if (this is PsiArrayType && this !is PsiEllipsisType) {
            node.append(componentType.build(NodeKind.Type), RefKind.Detail)
        }
        return node
    }

    fun PsiAnnotation.build(): DocumentationNode {
        val node = DocumentationNode(nameReferenceElement?.text ?: "<?>", Content.Empty, NodeKind.Annotation)
        parameterList.attributes.forEach {
            val parameter = DocumentationNode(it.name ?: "value", Content.Empty, NodeKind.Parameter)
            val value = it.value
            if (value != null) {
                val valueText = (value as? PsiLiteralExpression)?.value as? String ?: value.text
                val valueNode = DocumentationNode(valueText, Content.Empty, NodeKind.Value)
                parameter.append(valueNode, RefKind.Detail)
            }
            node.append(parameter, RefKind.Detail)
        }
        return node
    }
}

fun hasSuppressDocTag(element: Any?): Boolean {
    val declaration = (element as? KtLightDeclaration<*, *>)?.kotlinOrigin as? KtDeclaration ?: return false
    return PsiTreeUtil.findChildrenOfType(declaration.docComment, KDocTag::class.java).any { it.knownTag == KDocKnownTag.SUPPRESS }
}

/**
 * Determines if the @hide annotation is present in a Javadoc comment.
 *
 * @param element a doc element to analyze for the presence of @hide
 *
 * @return true if @hide is present, otherwise false
 *
 * Note: this does not process @hide annotations in KDoc.  For KDoc, use the @suppress tag instead, which is processed
 * by [hasSuppressDocTag].
 */
fun hasHideAnnotation(element: Any?): Boolean {
    return element is PsiDocCommentOwner && element.docComment?.run { findTagByName("hide") != null } ?: false
}