1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.tools.metalava.model.item 18 19 import com.android.tools.metalava.model.BaseModifierList 20 import com.android.tools.metalava.model.ItemDocumentation 21 import com.android.tools.metalava.model.ItemDocumentationFactory 22 import com.android.tools.metalava.model.PackageItem 23 import com.android.tools.metalava.reporter.FileLocation 24 25 /** Set of [PackageDoc] for every documented package defined in the source. */ 26 class PackageDocs( 27 private val packages: Map<String, PackageDoc>, 28 ) { 29 /** The set of package names. */ 30 val packageNames: Collection<String> = packages.keys 31 getnull32 operator fun get(packageName: String): PackageDoc { 33 return packages[packageName] ?: PackageDoc.EMPTY 34 } 35 36 companion object { 37 val EMPTY: PackageDocs = PackageDocs(emptyMap()) 38 } 39 } 40 41 /** Package specific documentation. */ 42 interface PackageDoc { 43 val fileLocation: FileLocation 44 val modifiers: BaseModifierList? 45 46 /** 47 * Factory for creating an [ItemDocumentation] instance containing the package level document. 48 * 49 * This factory will be invoked when creating the associated [PackageItem]. 50 * 51 * If specified this is used for [PackageItem.documentation]. 52 */ 53 val commentFactory: ItemDocumentationFactory? 54 55 /** 56 * The `overview.html` file. 57 * 58 * If specified this is used for [PackageItem.overviewDocumentation]. 59 */ 60 val overview: ResourceFile? 61 62 companion object { 63 val EMPTY = 64 object : PackageDoc { 65 override val fileLocation: FileLocation 66 get() = FileLocation.UNKNOWN 67 68 override val modifiers: BaseModifierList? 69 get() = null 70 71 override val commentFactory 72 get() = null 73 74 override val overview 75 get() = null 76 } 77 } 78 } 79 80 /** Mutable package specific documentation for use in [gatherPackageJavadoc]. */ 81 data class MutablePackageDoc( 82 val qualifiedName: String, 83 override var fileLocation: FileLocation = FileLocation.UNKNOWN, 84 override var modifiers: BaseModifierList? = null, 85 override var commentFactory: ItemDocumentationFactory? = null, 86 override var overview: ResourceFile? = null, 87 ) : PackageDoc 88