| /* |
| * Copyright 2020 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.google.devsite.renderer.converters |
| |
| import com.google.devsite.DocsSummaryList |
| import com.google.devsite.LinkDescriptionSummaryList |
| import com.google.devsite.className |
| import com.google.devsite.components.ContextFreeComponent |
| import com.google.devsite.components.DescriptionComponent |
| import com.google.devsite.components.Link |
| import com.google.devsite.components.impl.DefaultAnnotatedLink |
| import com.google.devsite.components.impl.DefaultDescriptionComponent |
| import com.google.devsite.components.impl.DefaultKmpTableRowSummaryItem |
| import com.google.devsite.components.impl.DefaultLink |
| import com.google.devsite.components.impl.DefaultParameterComponent |
| import com.google.devsite.components.impl.DefaultPlatformComponent |
| import com.google.devsite.components.impl.DefaultSummaryList |
| import com.google.devsite.components.impl.DefaultTableRowSummaryItem |
| import com.google.devsite.components.impl.DefaultTableTitle |
| import com.google.devsite.components.impl.DefaultTypeProjectionComponent |
| import com.google.devsite.components.impl.DefaultUnlink |
| import com.google.devsite.components.impl.UndocumentedSymbolDescriptionComponent |
| import com.google.devsite.components.symbols.AnnotatedLink |
| import com.google.devsite.components.symbols.ParameterComponent |
| import com.google.devsite.components.symbols.TypeProjectionComponent |
| import com.google.devsite.components.table.KmpTableRowSummaryItem |
| import com.google.devsite.components.table.SummaryList |
| import com.google.devsite.components.table.TableRowSummaryItem |
| import com.google.devsite.components.table.TableTitle |
| import com.google.devsite.renderer.Language |
| import com.google.devsite.renderer.impl.DocumentablesHolder |
| import com.google.devsite.renderer.impl.paths.FilePathProvider |
| import com.google.devsite.strictSingleOrNull |
| import org.jetbrains.dokka.DokkaConfiguration |
| import org.jetbrains.dokka.links.DRI |
| import org.jetbrains.dokka.model.Annotations |
| import org.jetbrains.dokka.model.Callable |
| import org.jetbrains.dokka.model.DClasslike |
| import org.jetbrains.dokka.model.DFunction |
| import org.jetbrains.dokka.model.DParameter |
| import org.jetbrains.dokka.model.DProperty |
| import org.jetbrains.dokka.model.DTypeAlias |
| import org.jetbrains.dokka.model.DTypeParameter |
| import org.jetbrains.dokka.model.DefinitelyNonNullable |
| import org.jetbrains.dokka.model.Documentable |
| import org.jetbrains.dokka.model.Dynamic |
| import org.jetbrains.dokka.model.JavaObject |
| import org.jetbrains.dokka.model.Nullable |
| import org.jetbrains.dokka.model.PrimitiveJavaType |
| import org.jetbrains.dokka.model.Projection |
| import org.jetbrains.dokka.model.Star |
| import org.jetbrains.dokka.model.StringValue |
| import org.jetbrains.dokka.model.TypeAliased |
| import org.jetbrains.dokka.model.TypeConstructor |
| import org.jetbrains.dokka.model.TypeParameter |
| import org.jetbrains.dokka.model.UnresolvedBound |
| import org.jetbrains.dokka.model.Variance |
| import org.jetbrains.dokka.model.Void |
| import org.jetbrains.dokka.model.WithChildren |
| import org.jetbrains.dokka.model.WithConstructors |
| import org.jetbrains.dokka.model.WithGenerics |
| import org.jetbrains.dokka.model.WithSources |
| import org.jetbrains.dokka.model.doc.Author |
| import org.jetbrains.dokka.model.doc.Constructor |
| import org.jetbrains.dokka.model.doc.CustomTagWrapper |
| import org.jetbrains.dokka.model.doc.Deprecated |
| import org.jetbrains.dokka.model.doc.Description |
| import org.jetbrains.dokka.model.doc.DocTag |
| import org.jetbrains.dokka.model.doc.DocumentationLink |
| import org.jetbrains.dokka.model.doc.NamedTagWrapper |
| import org.jetbrains.dokka.model.doc.P |
| import org.jetbrains.dokka.model.doc.Param |
| import org.jetbrains.dokka.model.doc.Pre |
| import org.jetbrains.dokka.model.doc.Property |
| import org.jetbrains.dokka.model.doc.Receiver |
| import org.jetbrains.dokka.model.doc.Return |
| import org.jetbrains.dokka.model.doc.Sample |
| import org.jetbrains.dokka.model.doc.See |
| import org.jetbrains.dokka.model.doc.Since |
| import org.jetbrains.dokka.model.doc.Suppress |
| import org.jetbrains.dokka.model.doc.TagWrapper |
| import org.jetbrains.dokka.model.doc.Text |
| import org.jetbrains.dokka.model.doc.Throws |
| import org.jetbrains.dokka.model.doc.Version |
| import java.io.File |
| |
| /** Extracts the handwritten documentation from documentables into the correct components. */ |
| internal class DocTagConverter( |
| private val displayLanguage: Language, |
| private val pathProvider: FilePathProvider, |
| private val docsHolder: DocumentablesHolder, |
| private val paramConverter: ParameterDocumentableConverter, |
| private val annotationConverter: AnnotationDocumentableConverter, |
| ) { |
| // We currently assume all sample are in the common sourceSet. TODO KMP samples b/181224204 |
| // private val analysisMap = runBlocking { docsHolder.analysisMap() } |
| |
| /** |
| * @param documentable the documentable we are getting the documentation of |
| * @param deprecationAnnotation the @Deprecated annotation. Is a parameter because for e.g. |
| * getters, the annotation will be propagated manually from some higher element, so we can't |
| * just use documentable.deprecationAnnotation() in such a case. |
| * @return the in-source hand-written element documentation |
| */ |
| fun summaryDescription( |
| documentable: Documentable, |
| deprecationAnnotation: Annotations.Annotation? = documentable.deprecationAnnotation(), |
| ): DescriptionComponent { |
| return deprecationComponent(documentable, summary = true, deprecationAnnotation) |
| ?: documentable.getDescription(summary = true) |
| } |
| |
| /** metadata() can either take a WithSources Documentable, OR an isFromJava boolean */ |
| fun <T> metadata( |
| documentable: T, |
| returnType: TypeProjectionComponent? = null, |
| paramNames: List<String> = emptyList(), |
| deprecationAnnotation: Annotations.Annotation? = documentable.deprecationAnnotation(), |
| ) where T : Documentable, T : WithSources = |
| metadataImpl(documentable, returnType, paramNames, deprecationAnnotation) |
| |
| fun metadata( |
| documentable: Documentable, |
| returnType: TypeProjectionComponent? = null, |
| paramNames: List<String> = emptyList(), |
| deprecationAnnotation: Annotations.Annotation? = documentable.deprecationAnnotation(), |
| isFromJava: Boolean, |
| ) = metadataImpl(documentable, returnType, paramNames, deprecationAnnotation, isFromJava) |
| |
| /** |
| * Returns a breakdown of the different metadata as a deprecation warning, description, and then |
| * separate summaries. Examples include the list of parameters, return type, see also, throws, |
| * etc. |
| */ |
| private fun metadataImpl( |
| documentable: Documentable, |
| returnType: TypeProjectionComponent? = null, |
| paramNames: List<String> = emptyList(), |
| deprecationAnnotation: Annotations.Annotation? = documentable.deprecationAnnotation(), |
| isFromJavaParam: Boolean? = null, |
| ): List<ContextFreeComponent> { |
| val isFromJava = if (isFromJavaParam != null) { |
| isFromJavaParam |
| } else { |
| assert(documentable is WithSources) |
| (documentable as WithSources).isFromJava() |
| } |
| val description = documentable.getDescription(summary = false) |
| val deprecation = deprecationComponent(documentable, summary = false, deprecationAnnotation) |
| val receiverParam = documentable.find<Receiver>()?.let { |
| Param(it.root, "receiver") |
| } |
| val generics = if (documentable is WithGenerics) documentable.generics else emptyList() |
| // Filter out tags which should instead be put into the Description, which is handled in the |
| // getDescription method. |
| val metadataTags = (listOfNotNull(receiverParam) + documentable.tags()) |
| .filter { !it.belongsInDescriptionOf(documentable) } |
| val tagsByType = metadataTags.sortedWith(tagOrder(paramNames)).groupBy { it.javaClass } |
| val tables = tagsByType.mapNotNull { (_, rawTags) -> |
| var tags = handleUpstreamTagDuplication(documentable, rawTags, generics) |
| if (tags.isEmpty()) return@mapNotNull null |
| val firstTag = tags.first() |
| if (documentable is DFunction && firstTag is Param) { |
| val propertyClass = Property::class.java as Class<*> |
| tags = tags + tagsByType[propertyClass].orEmpty() |
| } |
| // We know all the elements in `tags` will be of the same type, so we pick an arbitrary |
| // one to do the switching and then cast the list to its type. |
| @kotlin.Suppress("UNCHECKED_CAST") |
| try { |
| when (firstTag) { |
| is Param -> params( |
| tags as List<NamedTagWrapper>, |
| generics, |
| documentable, |
| isFromJava, |
| documentable.getExpectOrCommonSourceSet(), |
| ) |
| is Return -> returnType(tags as List<Return>, checkNotNull(returnType)) |
| is Throws -> throws(tags as List<Throws>, documentable) |
| is See -> see(tags as List<See>, documentable) |
| is Sample -> null // Samples are handled in the description |
| is Property -> |
| throw RuntimeException("Should have been consumed in description!") |
| is CustomTagWrapper -> docsHolder.printWarningFor( |
| "unrecognized javadoc tag @", |
| documentable, |
| brokenDocTag = firstTag, |
| ).let { null } |
| is Since -> docsHolder.printWarningFor( |
| "unsupported javadoc tag @", |
| documentable, |
| brokenDocTag = firstTag, |
| additionalContext = ". Instead, autogenerate per go/dackka#api-since.", |
| ).let { null } |
| is Constructor -> null // TODO("b/179999964: constructor") |
| is Description, is Deprecated -> null // Documented separately in getDescription |
| is Receiver -> null // gets merged with @params |
| is Suppress -> throw RuntimeException( |
| "Reaching the documentation generation step on a suppressed member should" + |
| "be impossible! If you see this, file a bug on dackka. $documentable", |
| ) |
| // These aren't tags we believe it is necessary to support |
| is Version, is Author -> null |
| } |
| } catch (e: Exception) { |
| throw RuntimeException( |
| "Exception thrown while handling ${firstTag.className} tags $tags.", |
| e, |
| ) |
| } |
| } |
| |
| return listOfNotNull(deprecation, description, *tables.toTypedArray()) |
| } |
| |
| // Turn both "E" and "<E>" to "E" |
| private fun ungenerify(name: String): String { |
| if (name.startsWith('<') && name.endsWith('>')) return name.drop(1).dropLast(1) |
| return name |
| } |
| private fun TagWrapper.name() = ungenerify((this as NamedTagWrapper).name) |
| private fun List<TagWrapper>.names() = this.map { it.name() } |
| |
| /* Tags, in particular for property parameters, are propagated multiple times in upstream. |
| * For example, @param t t_doc class Foo(val t) has Parameter(t, t_doc) duplicated many times. |
| * On the class itself, on each property parameter of that class, and on the constructor. |
| * This function filters out inappropriately propagated docs, and enforces that documentation |
| * applies only to existing properties and parameters. |
| */ |
| private fun handleUpstreamTagDuplication( |
| documentable: Documentable, |
| tags: List<TagWrapper>, |
| generics: List<DTypeParameter>, |
| ): List<TagWrapper> { |
| if (tags.first() is Param) { |
| // This one is very strange, and I haven't been able to reproduce it in unit tests |
| // A generic called "ToValue" is instead registered as being named "V" |
| // TODO: Fix |
| if (tags.names() == listOf("ToValue", "function") && generics.single().name == "V") { |
| return tags.filter { (it as Param).name == "function" } |
| } |
| |
| // Handle parameter properties, e.g. class AClass<Gen>(val propParam) |
| when (documentable) { |
| // doc is DClasslike. DClasslike's only valid @params are type params |
| is DClasslike -> { |
| val genericNames = generics.map { it.name } |
| val (forGenerics, otherAtParams) = tags.partition { it.name() in genericNames } |
| if (otherAtParams.isEmpty()) return forGenerics |
| // Enforce that the propagated documentation makes sense somewhere. Specifically |
| // documentation primarily aimed at a constructor may wind up on the DClass |
| // if the parameter being documented is a primary constructor property parameter |
| val constructorParamNames = (documentable as? WithConstructors)?.constructors |
| ?.map { constructor -> constructor.parameters.map { it.name!! } }?.flatten() |
| .orEmpty() |
| val otherNames = |
| (documentable.properties.map { it.name } + constructorParamNames) |
| val (validTags, badTags) = otherAtParams.partition { it.name() in otherNames } |
| badTags.forEach { |
| docsHolder.printWarningFor( |
| "Unable to find reference @", |
| documentable, |
| brokenDocTag = it, |
| additionalContext = |
| ". Are you trying to refer to something not visible to users?", |
| ) |
| } |
| // Use only docs for type parameters in the parameter documentation table |
| return forGenerics |
| } |
| // doc is Property. It is possible that a parameter property is documented on the |
| // class as @param. That doc is used as though it were @property. Handled there. |
| // Properties can also have @param documentation for type parameters |
| is DProperty -> { |
| val genericNames = generics.map { it.name } |
| val (forGenericsOrThis, badTags) = tags |
| .partition { it.name() in genericNames || it.name() == documentable.name } |
| badTags.forEach { |
| docsHolder.printWarningFor( |
| "Unable to find reference @", |
| documentable, |
| brokenDocTag = it, |
| additionalContext = |
| ". Are you trying to refer to something not visible to users?", |
| ) |
| } |
| return forGenericsOrThis |
| } |
| is DFunction -> {} |
| else -> |
| throw RuntimeException("Can't apply @param to a ${documentable.className}") |
| } |
| } else if (tags.first() is Property) { |
| // A DClasslike with @property applying to property parameters may have Parameter tags |
| // In such a case, none of these tags should become docs *on the DClasslike itself* |
| return when (documentable) { |
| is DClasslike -> { |
| val propertyNames = documentable.properties.map { it.name } |
| tags.filter { it.name() !in propertyNames }.forEach { |
| docsHolder.printWarningFor( |
| "Unable to find reference @", |
| documentable, |
| brokenDocTag = it, |
| ) |
| } |
| emptyList() |
| } |
| |
| is DParameter, is DProperty -> tags |
| else -> |
| throw RuntimeException("Can't apply @property to a ${documentable.className}") |
| } |
| } |
| return tags |
| } |
| |
| private fun params( |
| tags: List<NamedTagWrapper>, |
| dGenerics: List<DTypeParameter>, |
| documentable: Documentable, |
| isFromJava: Boolean, |
| sourceSet: DokkaConfiguration.DokkaSourceSet, |
| ): DocsSummaryList { |
| val tagged = tags.map { it.name() }.toSet() |
| |
| // @param can refer to parameters, lambda parameters, type parameters, or receivers. |
| val allOptions = mutableMapOf<String, ParameterComponent>() |
| if (documentable is DFunction) { |
| allOptions.putAll( |
| documentable.parameters.mapNotNull { |
| val name = it.name!! |
| if (!tagged.contains(name)) { |
| // Synthetic receiver params don't need @param documentation |
| if (name == "receiver") return@mapNotNull null |
| docsHolder.printWarningFor( |
| "Missing @param tag for parameter `$name`", |
| documentable, |
| ) |
| } |
| name to paramConverter.componentForParameter( |
| param = it, |
| isSummary = false, |
| isFromJava = isFromJava, |
| parent = documentable, |
| ) |
| }, |
| ) |
| allOptions.putAll( |
| recursivelyGetLambdaParamNames(documentable.parameters.map { it.type }).map { |
| (it.presentableName ?: "") to paramConverter |
| .componentForLambdaParameter(it, isFromJava, sourceSet) |
| }, |
| ) |
| } |
| allOptions.putAll( |
| dGenerics.map { |
| it.name to paramConverter.componentForTypeParameter(it, isFromJava) |
| }, |
| ) |
| if (documentable is Callable && documentable.receiver != null) { |
| allOptions[documentable.receiver!!.name ?: "receiver"] = |
| paramConverter.componentForParameter( |
| param = documentable.receiver!!, |
| isSummary = false, |
| isFromJava = isFromJava, |
| parent = documentable, |
| ) |
| } |
| val params = tags.map { tag -> |
| if (allOptions[tag.name()] == null) { |
| throw RuntimeException( |
| "Unable to find what is referred to by \"@param " + |
| "${tag.name()}\" in ${documentable.className} " + |
| "${documentable.name}, with contents: ${tag.text()}", |
| ) |
| } |
| val title = allOptions[tag.name()]!! |
| DefaultTableRowSummaryItem( |
| TableRowSummaryItem.Params( |
| title = title, |
| description = description(tag), |
| ), |
| ) |
| } |
| |
| return DefaultSummaryList( |
| SummaryList.Params( |
| header = DefaultTableTitle(TableTitle.Params("Parameters")), |
| items = params, |
| ), |
| ) |
| } |
| |
| /** For example, "a" and "b" in `fun foo((a: (b: String) -> int)) -> Unit)` */ |
| private fun recursivelyGetLambdaParamNames( |
| argumentTypes: List<Projection>, |
| ): List<TypeConstructor> { |
| val result = mutableListOf<TypeConstructor>() |
| for (argumentType in argumentTypes) { |
| when (argumentType) { |
| is TypeConstructor -> { |
| if (argumentType.presentableName != null) result += argumentType |
| result += recursivelyGetLambdaParamNames(argumentType.projections) |
| } |
| is Variance<*> -> { |
| result += recursivelyGetLambdaParamNames(listOf(argumentType.inner)) |
| } |
| is Nullable -> { |
| result += recursivelyGetLambdaParamNames(listOf(argumentType.inner)) |
| } |
| is DefinitelyNonNullable -> { |
| result += recursivelyGetLambdaParamNames(listOf(argumentType.inner)) |
| } |
| is TypeParameter -> { |
| /* Type parameters can't be lambdas, and are fully squashed to strings. */ |
| } |
| is TypeAliased -> { // No clear way to decide which |
| result += recursivelyGetLambdaParamNames( |
| setOf(argumentType.inner, argumentType.typeAlias).toList(), |
| ) |
| } |
| is PrimitiveJavaType, is JavaObject, Void, Dynamic, Star -> { /* Do nothing */ } |
| is UnresolvedBound -> { /* Nothing we can do. We warn elsewhere for this case. */ } |
| } |
| } |
| return result |
| } |
| |
| private fun returnType(tags: List<Return>, returnType: TypeProjectionComponent): |
| SummaryList<TableRowSummaryItem<TypeProjectionComponent, DescriptionComponent>> { |
| val params = tags.map { tag -> |
| DefaultTableRowSummaryItem( |
| TableRowSummaryItem.Params( |
| title = returnType, |
| description = description(tag), |
| ), |
| ) |
| } |
| |
| return DefaultSummaryList( |
| SummaryList.Params( |
| header = DefaultTableTitle(TableTitle.Params("Returns")), |
| items = params, |
| ), |
| ) |
| } |
| |
| private fun throws(tags: List<Throws>, parent: Documentable): DocsSummaryList { |
| val params = tags.map { tag -> |
| DefaultTableRowSummaryItem( |
| TableRowSummaryItem.Params( |
| title = throwsToParameterComponent(tag, parent), |
| description = description(tag), |
| ), |
| ) |
| } |
| |
| return DefaultSummaryList( |
| SummaryList.Params( |
| header = DefaultTableTitle(TableTitle.Params("Throws")), |
| items = params, |
| ), |
| ) |
| } |
| |
| private fun String.firstWord() = substring(0, indexOfFirst { it == ' ' }) |
| |
| private fun throwsToParameterComponent( |
| throws: Throws, |
| parent: Documentable, |
| ): ParameterComponent { |
| val name = throws.name |
| var dri: DRI? = throws.exceptionAddress |
| if (throws.name in listOf("a", "an")) { |
| throw RuntimeException( |
| "Do not use '${throws.name}' before the exception type in an @throws statement. " + |
| "This is against jdoc spec. Your exception is not being linked and looks bad", |
| ) |
| } else if ("{@link" in name) { |
| throw RuntimeException( |
| "Do not {@link the exception type in an @throws statement. @throws state" + |
| "ments are automatically linked. Manually java-linking them is against jdoc s" + |
| "pec, and breaks linking behavior causing them to actually *not* be linked.", |
| ) |
| } else if (throws.exceptionAddress == null) { |
| docsHolder.printWarningFor( |
| "Link does not resolve for @", |
| parent, |
| brokenDocTag = throws, |
| additionalContext = ". Is it from a package that the containing file does not " + |
| "import? Are docs inherited by an un-documented override function, but the " + |
| "exception class is not in scope in the inheriting class? The general fix for" + |
| " these is to fully qualify the exception name, e.g. " + |
| "`@throws java.io.IOException under some conditions`.", |
| ) |
| dri = null |
| } |
| val link = if (dri == null) { |
| DefaultLink(Link.Params(name, url = "")) |
| } else pathProvider.linkForReference(throws.exceptionAddress!!, name) |
| |
| return DefaultParameterComponent( |
| ParameterComponent.Params( |
| name = "", |
| type = DefaultTypeProjectionComponent( |
| TypeProjectionComponent.Params( |
| type = link, |
| nullability = Nullability.DONT_CARE, |
| displayLanguage = displayLanguage, |
| ), |
| ), |
| displayLanguage = displayLanguage, |
| ), |
| ) |
| } |
| |
| private fun see(tags: List<See>, parent: Documentable): LinkDescriptionSummaryList { |
| val params = tags.map { tag -> |
| DefaultTableRowSummaryItem( |
| TableRowSummaryItem.Params( |
| title = tag.toLink(parent), |
| description = description(tag), |
| ), |
| ) |
| } |
| |
| return DefaultSummaryList( |
| SummaryList.Params( |
| header = DefaultTableTitle(TableTitle.Params("See also")), |
| items = params, |
| ), |
| ) |
| } |
| |
| /** |
| * Gets a Description for the Documentable, or returns UndocumentedSymbolDescription() |
| * Has special handling to inject @property documentation as a description, if it exists |
| * Also applies to @param documentation that should become a description, i.e. property params |
| */ |
| private fun Documentable.getDescription(summary: Boolean): DescriptionComponent { |
| val components = mutableListOf<DocTag>() |
| tags().forEach { |
| when (it) { |
| is Sample -> { |
| val dri = it.name |
| // val sourceSet = this.getExpectOrCommonSourceSet() |
| /* val analysisEnvironment = analysisMap[sourceSet]!! |
| val sample = try { |
| analysisEnvironment |
| .resolveSample(sourceSet, dri)!! |
| } catch (e: NullPointerException) { |
| throw RuntimeException("Unable to resolve sample $dri!") |
| }*/ |
| // TODO(KMP) we currently have no plan to provide KMP samples b/181224204 |
| // As such, we currently assume that all samples are in common |
| val sample = docsHolder.sampleAnalysisEnvironment |
| .resolveSample(docsHolder.commonSourceSet, dri)!! |
| val imports = processImports(sample) |
| |
| components.add( |
| Pre( |
| params = mapOf("class" to "prettyprint lang-kotlin"), |
| children = listOf(Text(imports + sample.body)), |
| ), |
| ) |
| components.addAll(it.children) |
| } |
| is Description, is NamedTagWrapper -> { |
| if (!it.belongsInDescriptionOf(this)) return@forEach |
| it.children.forEach { child -> |
| try { |
| recursivelyConsiderPsAndTextsForJavaSamples( |
| child, |
| components, |
| this.getExpectOrCommonSourceSet().samples, |
| ) |
| } catch (e: Exception) { |
| throw RuntimeException( |
| "Error when resolving samples when processing $name", |
| e, |
| ) |
| } |
| } |
| } |
| is Author, is Version -> {} // These are not supported |
| is Return, is Receiver, is Constructor -> {} // These become tables in metadata() |
| is Deprecated, is Suppress, is Since -> {} // These are handled elsewhere |
| } |
| } |
| if (components.isEmpty()) return UndocumentedSymbolDescriptionComponent |
| return description(components, summary, null) |
| } |
| |
| /** |
| * Tags with the same name as the documentable should generally go in the description component, |
| * but sometimes the tag refers to something else with the same name, like a parameter that has |
| * the same name as its function. |
| */ |
| private fun TagWrapper.belongsInDescriptionOf(documentable: Documentable): Boolean { |
| if (this is Description) return true |
| if (this !is NamedTagWrapper) return false |
| return when (this) { |
| is Param, is Property -> (documentable is DParameter || documentable is DProperty) && |
| (this.name == documentable.name) |
| is Throws, is See -> false |
| else -> true |
| } |
| } |
| |
| /** annotation-sampled and SampledAnnotationDetector */ |
| private fun DocTag.explicitlyBanLookingForSamples() = |
| "Functions referenced with @sample are annotated with @Sampled" in text() || |
| "Denotes that the annotated function is considered a sample function" in text() || |
| "that functions referred to from KDoc with a @sample tag are annotated" in text() |
| |
| private fun recursivelyConsiderPsAndTextsForJavaSamples( |
| root: DocTag, |
| components: MutableList<DocTag>, |
| samples: Set<File>, |
| ) { |
| if ("@sample" !in root.text() || root.explicitlyBanLookingForSamples()) { |
| components.add(root) |
| return |
| } |
| when (root) { |
| is Text -> { |
| val parts = root.body.split("{", "}") |
| for (part in parts) { |
| if ("@sample" !in part) { |
| if (part.isNotBlank()) components.add(Text(part.trim())) |
| } else components.add(convertTextToJavadocSample(Text(part.trim()), samples)) |
| } |
| } |
| is P -> { |
| for (child in root.children) { |
| recursivelyConsiderPsAndTextsForJavaSamples(child, components, samples) |
| } |
| } |
| // Having non-text components on the same line as a samples is not supported |
| else -> throw RuntimeException("considered invalid type ${root.className} for sample") |
| } |
| } |
| |
| private fun WithChildren<DocTag>.text(): String { |
| return if (this is Text) this.body else children.joinToString(" ") { it.text() } |
| } |
| |
| private fun description( |
| soleComponent: TagWrapper, |
| summary: Boolean = false, |
| deprecation: String? = null, |
| ): DescriptionComponent { |
| return description(soleComponent.children, summary, deprecation) |
| } |
| |
| private fun description( |
| components: List<DocTag> = emptyList(), |
| summary: Boolean = false, |
| deprecation: String? = null, |
| ): DescriptionComponent { |
| return DefaultDescriptionComponent( |
| DescriptionComponent.Params( |
| pathProvider, |
| components, |
| summary, |
| deprecation, |
| docsHolder, |
| ), |
| ) |
| } |
| |
| /** Returns the component for a deprecation. */ |
| private fun deprecationComponent( |
| documentable: Documentable, |
| summary: Boolean, |
| deprecationAnnotation: Annotations.Annotation?, |
| ): DescriptionComponent? { |
| val deprecation = findDeprecation(documentable, deprecationAnnotation) ?: return null |
| return description(deprecation.children, summary, documentable.deprecationText()) |
| } |
| |
| /** |
| * Finds either the javadoc @deprecated tag or the Kotlin @Deprecated annotation [TagWrapper]. |
| */ |
| private fun findDeprecation( |
| documentable: Documentable, |
| deprecationAnnotation: Annotations.Annotation?, |
| ): Deprecated? { |
| val javadocDeprecation = documentable.find<Deprecated>() |
| if (javadocDeprecation != null) { |
| // Prefer javadoc deprecation messages since they allow formatting |
| return javadocDeprecation |
| } |
| |
| val annotationDeprecationMessage = |
| (deprecationAnnotation?.params?.get("message") as? StringValue)?.value ?: return null |
| // Dokka makes message="foo" show up as "\"foo\"" since you typically want to show quotes |
| // when rendering an annotation. Remove those outer quotes. |
| val message = annotationDeprecationMessage.removeSurrounding("\"") |
| |
| return Deprecated(P(children = listOf(Text(message)))) |
| } |
| |
| private fun Documentable.deprecationText() = |
| "This ${this.stringForType(displayLanguage)} is deprecated." |
| |
| /** Retrieves the doc tags of type [T]. */ |
| private inline fun <reified T> Documentable.find() = |
| tags().filterIsInstance<T>().strictSingleOrNull() |
| |
| /** |
| * @return the doc tags (aka human-written javadoc or kdoc) associated with this documentable |
| */ |
| private fun Documentable.tags() = documentation[getExpectOrCommonSourceSet()]?.children |
| ?: emptyList() |
| |
| private fun tagOrder(paramNames: List<String>) = compareBy<TagWrapper> { tag -> |
| when (tag) { |
| is Deprecated -> 0 |
| is Description -> 1 |
| is Return -> 2 |
| is Constructor -> 3 |
| is Property -> 4 |
| is Receiver -> 5 |
| is Param -> 6 |
| is Throws -> 7 |
| is See -> 8 |
| is Sample -> 9 |
| is Since -> 10 |
| is Version -> 11 |
| is Author -> 12 |
| is Suppress -> 13 |
| is CustomTagWrapper -> 14 |
| } |
| }.thenBy { tag -> |
| when (tag) { |
| is Param -> paramNames.indexOf(tag.name) |
| else -> -1 |
| } |
| } |
| |
| /** |
| * Extract the see tag's reference into a link. |
| * |
| * This one is painful. An address is only sometimes there, other times there's a docs link |
| * nested somewhere in the tree, and as a last resort the name is always present with whatever |
| * a developer writes which could either be a fully qualified reference or just the URL |
| * fragment. |
| */ |
| private fun See.toLink(parent: Documentable): Link { |
| val address = address |
| if (address != null) { |
| return pathProvider.linkForReference(address) |
| } |
| val docsLink = root.explodedChildren.filterIsInstance<DocumentationLink>().singleOrNull() |
| if (docsLink != null) { |
| return pathProvider.linkForReference(docsLink.dri) |
| } |
| |
| // TODO(b/167437580): figure out how to reliably parse links |
| val segments = name.split("#") |
| return if (segments.size == 1) { |
| val (packageName, typeName) = typeToPackageNameAndType(segments.single()) |
| if (typeName.isEmpty()) { |
| var additionalContext = "" |
| // Maybe the link is `package.Class.aFunction` instead of `package.Class#aFunction`? |
| val last = name.substringAfterLast(".") |
| val rest = name.substringBeforeLast(".") |
| if (last.firstOrNull()?.isLowerCase() == true && rest.any { it.isUpperCase() }) { |
| additionalContext = ". Did you mean $rest#$last?" |
| val (packageN, typeN) = typeToPackageNameAndType(rest) |
| val url = pathProvider.forType(packageN, typeN) |
| DefaultLink(Link.Params(typeN, "$url#$last")) |
| } |
| docsHolder.printWarningFor( |
| "Failed to resolve ", |
| parent, |
| brokenDocTag = this, |
| additionalContext = additionalContext, |
| ) |
| DefaultLink(Link.Params(name, url = "")) |
| } else if (packageName.isEmpty()) { |
| // This is a same-package type link, though we sadly can't prove it's correct |
| pathProvider.linkForReference(DRI("", typeName)) |
| } else { |
| pathProvider.linkForReference(DRI(packageName, typeName)) |
| } |
| } else if (segments.size == 2) { |
| val (type, anchor) = segments |
| if (type.isEmpty()) { |
| // Self link |
| DefaultLink(Link.Params(anchor, anchor)) |
| } else { |
| // Assume link with anchor |
| val (packageName, typeName) = typeToPackageNameAndType(type) |
| val url = pathProvider.forType(packageName, typeName) |
| DefaultLink(Link.Params(typeName, "$url#$anchor")) |
| } |
| } else { |
| throw RuntimeException("Could not understand path: $name") |
| } |
| } |
| |
| /** Horrible guess-work to try and extract the package and type names. */ |
| private fun typeToPackageNameAndType(full: String): Pair<String, String> { |
| val parts = full.split(".") |
| |
| if (parts.size == 1) return "" to full |
| |
| val packageName = parts.takeWhile { it.all(Char::isLowerCase) }.joinToString(".") |
| val typeName = parts.takeLastWhile { |
| if (it.isEmpty()) { |
| throw RuntimeException("empty element in TTPNAT. Full: $full") |
| } else it.first().isUpperCase() |
| }.joinToString(".") |
| return packageName to typeName |
| } |
| |
| internal fun docsToSummaryDefault(documentables: List<Documentable>) = |
| docsToSummary(documentables, false) |
| |
| /** |
| * Converts a generic List<Documentable> to a SummaryList. |
| * Does nothing clever; only converts Documentables to links (by default with annotations) |
| */ |
| private fun docsToSummary( |
| documentables: List<Documentable>, |
| showAnnotations: Boolean, |
| ) = DefaultSummaryList( |
| SummaryList.Params( |
| items = documentables |
| .map { summaryForDocumentable(it, showAnnotations) }, |
| ), |
| ) |
| |
| /** |
| * Converts generic Documentables to TableRowSummaryItems, as simple maybe-annotated links |
| * This is used for mini-signatures, e.g. nested types list, subclasses list, package summary |
| */ |
| internal fun summaryForDocumentable( |
| documentable: Documentable, |
| showAnnotations: Boolean = false, |
| ): TableRowSummaryItem<Link, DescriptionComponent> { |
| val link = if (documentable is DTypeAlias) { |
| // typealiases have no pages |
| DefaultUnlink(Link.Params(documentable.name, "")) |
| } else pathProvider.linkForReference(documentable.dri) |
| val maybeAnnotatedLink = if (showAnnotations) { |
| DefaultAnnotatedLink( |
| AnnotatedLink.Params( |
| annotations = annotationConverter.annotationComponents( |
| documentable.annotations(documentable.getExpectOrCommonSourceSet()), |
| nullability = Nullability.DONT_CARE, // Not useful for these cases |
| ), |
| link = link, |
| ), |
| ) |
| } else { |
| link |
| } |
| return DefaultTableRowSummaryItem( |
| TableRowSummaryItem.Params( |
| title = maybeAnnotatedLink, |
| description = summaryDescription( |
| documentable, |
| documentable.deprecationAnnotation(), |
| ), |
| ), |
| ) |
| } |
| |
| /** |
| * Converts a generic List<Documentable> to a SummaryList. |
| * Does nothing clever; only converts Documentables to links (by default with annotations) |
| */ |
| internal fun docsToSummaryKmp( |
| documentables: List<Documentable>, |
| ) = DefaultSummaryList( |
| SummaryList.Params( |
| items = documentables |
| .map { summaryForDocumentableKmp(it) }, |
| ), |
| ) |
| |
| /** |
| * Converts generic Documentables to TableRowSummaryItems, as simple maybe-annotated links |
| * This is used for mini-signatures, e.g. nested types list, subclasses list, package summary |
| */ |
| private fun summaryForDocumentableKmp( |
| documentable: Documentable, |
| ): TableRowSummaryItem<Link, DescriptionComponent> { |
| return DefaultKmpTableRowSummaryItem( |
| KmpTableRowSummaryItem.Params( |
| title = pathProvider.linkForReference(documentable.dri), |
| description = summaryDescription(documentable), |
| platforms = DefaultPlatformComponent(documentable.sourceSets), |
| ), |
| ) |
| } |
| } |
