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
18 
19 import com.github.ajalt.clikt.parameters.groups.OptionGroup
20 import com.github.ajalt.clikt.parameters.options.multiple
21 import com.github.ajalt.clikt.parameters.options.option
22 
23 const val ARG_SHOW_ANNOTATION = "--show-annotation"
24 const val ARG_SHOW_SINGLE_ANNOTATION = "--show-single-annotation"
25 const val ARG_SHOW_FOR_STUB_PURPOSES_ANNOTATION = "--show-for-stub-purposes-annotation"
26 
27 /** The name of the group, can be used in help text to refer to the options in this group. */
28 const val API_SELECTION_OPTIONS_GROUP = "Api Selection"
29 
30 /**
31  * Options related to selecting which parts of the source files will be part of the generated API.
32  */
33 class ApiSelectionOptions() :
34     OptionGroup(
35         name = API_SELECTION_OPTIONS_GROUP,
36         help =
37             """
38                 Options that select which parts of the source files will be part of the generated
39                 API.
40             """
41                 .trimIndent()
42     ) {
43 
44     private val showAnnotationValues by
45         option(
46                 ARG_SHOW_ANNOTATION,
47                 help =
48                     """
49                         Unhide any hidden elements that are also annotated with the given
50                         annotation.
51                     """
52                         .trimIndent(),
53                 metavar = "<annotation-filter>",
54             )
55             .multiple()
56 
57     private val showSingleAnnotationValues by
58         option(
59                 ARG_SHOW_SINGLE_ANNOTATION,
60                 help =
61                     """
62                         Like $ARG_SHOW_ANNOTATION, but does not apply to members; these must also be
63                         explicitly annotated.
64                     """
65                         .trimIndent(),
66                 metavar = "<annotation-filter>",
67             )
68             .multiple()
69 
70     private val showForStubPurposesAnnotationValues by
71         option(
72                 ARG_SHOW_FOR_STUB_PURPOSES_ANNOTATION,
73                 help =
74                     """
75                         Like $ARG_SHOW_ANNOTATION, but elements annotated with it are assumed to be
76                         "implicitly" included in the API surface, and they'll be included in certain
77                         kinds of output such as stubs, but not in others, such as the signature file
78                         and API lint.
79                     """
80                         .trimIndent(),
81                 metavar = "<annotation-filter>",
82             )
83             .multiple()
84 
85     /**
86      * Whether to include APIs with annotations (intended for documentation purposes). This includes
87      * [showAnnotations], [showSingleAnnotations] and [showForStubPurposesAnnotations].
88      */
89     internal val allShowAnnotations by
<lambda>null90         lazy(LazyThreadSafetyMode.NONE) {
91             AnnotationFilter.create(
92                 showAnnotationValues +
93                     showSingleAnnotationValues +
94                     showForStubPurposesAnnotationValues
95             )
96         }
97 
98     /**
99      * A filter that will match annotations which will cause an annotated item (and its enclosed
100      * items unless overridden by a closer annotation) to be included in the API surface.
101      *
102      * @see [allShowAnnotations]
103      */
104     internal val showAnnotations by
<lambda>null105         lazy(LazyThreadSafetyMode.NONE) { AnnotationFilter.create(showAnnotationValues) }
106 
107     /**
108      * Like [showAnnotations], but does not work recursively.
109      *
110      * @see [allShowAnnotations]
111      */
112     internal val showSingleAnnotations by
<lambda>null113         lazy(LazyThreadSafetyMode.NONE) { AnnotationFilter.create(showSingleAnnotationValues) }
114 
115     /**
116      * Annotations that defines APIs that are implicitly included in the API surface. These APIs
117      * will be included in certain kinds of output such as stubs, but others (e.g. API lint and the
118      * API signature file) ignore them.
119      *
120      * @see [allShowAnnotations]
121      */
122     internal val showForStubPurposesAnnotations by
<lambda>null123         lazy(LazyThreadSafetyMode.NONE) {
124             AnnotationFilter.create(showForStubPurposesAnnotationValues)
125         }
126 }
127