1 /*
2  * Copyright (C) 2017 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
18 
19 @MetalavaApi
20 interface ParameterItem : Item {
21     /** The name of this field */
namenull22     fun name(): String
23 
24     /** The type of this field */
25     @MetalavaApi override fun type(): TypeItem
26 
27     override fun findCorrespondingItemIn(
28         codebase: Codebase,
29         superMethods: Boolean,
30         duplicate: Boolean,
31     ) =
32         containingMethod()
33             .findCorrespondingItemIn(codebase, superMethods = superMethods, duplicate = duplicate)
34             ?.parameters()
35             ?.getOrNull(parameterIndex)
36 
37     /** The containing method */
38     fun containingMethod(): MethodItem
39 
40     /** Index of this parameter in the parameter list (0-based) */
41     val parameterIndex: Int
42 
43     /**
44      * The public name of this parameter. In Kotlin, names are part of the public API; in Java they
45      * are not. In Java, you can annotate a parameter with {@literal @ParameterName("foo")} to name
46      * the parameter something (potentially different from the actual code parameter name).
47      */
48     fun publicName(): String?
49 
50     /**
51      * Returns whether this parameter has a default value. In Kotlin, this is supported directly; in
52      * Java, it's supported via a special annotation, {@literal @DefaultValue("source"). This does
53      * not necessarily imply that the default value is accessible, and we know the body of the
54      * default value.
55      *
56      * @see isDefaultValueKnown
57      */
58     fun hasDefaultValue(): Boolean
59 
60     /**
61      * Returns whether this parameter has an accessible default value that we plan to keep. This is
62      * a superset of [hasDefaultValue] - if we are not writing the default values to the signature
63      * file, then the default value might not be available, even though the parameter does have a
64      * default.
65      *
66      * @see hasDefaultValue
67      */
68     fun isDefaultValueKnown(): Boolean
69 
70     /**
71      * Returns the default value.
72      *
73      * **This method should only be called if [isDefaultValueKnown] returned true!** (This is
74      * necessary since the null return value is a valid default value separate from no default value
75      * specified.)
76      *
77      * The default value is the source string literal representation of the value, e.g. strings
78      * would be surrounded by quotes, Booleans are the strings "true" or "false", and so on.
79      */
80     fun defaultValue(): String?
81 
82     /** Whether this is a varargs parameter */
83     fun isVarArgs(): Boolean
84 
85     /** The property declared by this parameter; inverse of [PropertyItem.constructorParameter] */
86     val property: PropertyItem?
87         get() = null
88 
89     override fun parent(): MethodItem? = containingMethod()
90 
91     override val effectivelyDeprecated: Boolean
92         get() = originallyDeprecated || containingMethod().effectivelyDeprecated
93 
94     override fun baselineElementId() =
95         containingMethod().baselineElementId() + " parameter #" + parameterIndex
96 
97     override fun accept(visitor: ItemVisitor) {
98         visitor.visit(this)
99     }
100 
toStringForItemnull101     override fun toStringForItem() = "parameter ${name()}"
102 
103     override fun containingClass(): ClassItem = containingMethod().containingClass()
104 
105     override fun containingPackage(): PackageItem? = containingMethod().containingPackage()
106 
107     // TODO: modifier list
108 }
109