Add help signature-file-formats
Provides some general information about signature files and refers to
the `FORMAT.md` for more information.
Bug: 295829461
Test: ./gradlew
Change-Id: I0ec1cc6c8d4ca7f31e1633e04b0324dcbe5a502c
diff --git a/src/main/java/com/android/tools/metalava/cli/help/HelpCommand.kt b/src/main/java/com/android/tools/metalava/cli/help/HelpCommand.kt
index 537ef47..1540d33 100644
--- a/src/main/java/com/android/tools/metalava/cli/help/HelpCommand.kt
+++ b/src/main/java/com/android/tools/metalava/cli/help/HelpCommand.kt
@@ -20,6 +20,8 @@
import com.android.tools.metalava.cli.common.MetalavaHelpFormatter
import com.android.tools.metalava.cli.common.stdout
import com.android.tools.metalava.cli.common.terminal
+import com.android.tools.metalava.cli.signature.ARG_API_OVERLOADED_METHOD_ORDER
+import com.android.tools.metalava.cli.signature.ARG_FORMAT
import com.github.ajalt.clikt.core.CliktCommand
import com.github.ajalt.clikt.core.context
import com.github.ajalt.clikt.core.subcommands
@@ -52,6 +54,7 @@
subcommands(
IssuesCommand(),
packageFilterHelp,
+ signatureFileFormatsHelp,
)
}
@@ -89,3 +92,61 @@
"""
.trimIndent()
)
+
+private val signatureFileFormatsHelp =
+ SimpleHelpCommand(
+ name = "signature-file-formats",
+ help =
+ """
+Describes the different signature file formats.
+
+See `FORMAT.md` in the top level metalava directory for more information.
+
+Conceptually, a signature file format is a set of properties that determine the types of information
+that will be output to the API signature file and how it is represented. A format version is simply
+a set of defaults for those properties.
+
+The supported properties are:
+
+* `kotlin-style-nulls = yes|no` - if `no` then the signature file will use `@Nullable` and `@NonNull`
+ annotations to indicate that the annotated item accepts `null` and does not accept `null`
+ respectively and neither indicates that it's not defined.
+
+ If `yes` then the signature file will use a type suffix of `?`, no type suffix and a type suffix
+ of `!` to indicate the that the type accepts `null`, does not accept `null` or it's not defined
+ respectively.
+
+* `concise-default-values = yes|no` - if `no` then Kotlin parameters that have a default value will
+ include that value in the signature file. If `yes` then those parameters will simply be prefixed
+ with `optional`, as if it was a keyword and no value will be included.
+
+Currently, metalava supports the following versions:
+
+* `2.0` ($ARG_FORMAT=v2) - this is the base version (more details in `FORMAT.md`) on which all the
+ others are based. It sets the properties as follows:
+```
++ kotlin-style-nulls = no
++ concise-default-values = no
+```
+
+* `3.0` ($ARG_FORMAT=v3) - this is `2.0` plus `kotlin-style-nulls = yes` giving the following
+properties:
+```
++ kotlin-style-nulls = yes
++ concise-default-values = no
+```
+
+* `4.0` ($ARG_FORMAT=v4) - this is 3.0` plus `concise-default-values = yes` giving the following
+properties:
+```
++ kotlin-style-nulls = yes
++ concise-default-values = yes
+```
+
+The `$ARG_API_OVERLOADED_METHOD_ORDER` option also affects the contents in the signature file, i.e.
+whether overloaded methods are sorted based on their source order or purely based on their
+signature. However, it is orthogonal to a specific version and should be considered as purely a
+temporary measure, provided to aid migration and as such will be removed at some time in future.
+ """
+ .trimIndent()
+ )
diff --git a/src/main/java/com/android/tools/metalava/cli/signature/SignatureFormatOptions.kt b/src/main/java/com/android/tools/metalava/cli/signature/SignatureFormatOptions.kt
index f978a97..12a0e36 100644
--- a/src/main/java/com/android/tools/metalava/cli/signature/SignatureFormatOptions.kt
+++ b/src/main/java/com/android/tools/metalava/cli/signature/SignatureFormatOptions.kt
@@ -127,7 +127,13 @@
class SignatureFormatOptions :
OptionGroup(
name = SIGNATURE_FORMAT_OUTPUT_GROUP,
- help = "Options controlling the format of the generated signature files."
+ help =
+ """
+ Options controlling the format of the generated signature files.
+
+ See `metalava help signature-file-formats` for more information.
+ """
+ .trimIndent()
) {
/**
diff --git a/src/test/java/com/android/tools/metalava/cli/help/HelpCommandTest.kt b/src/test/java/com/android/tools/metalava/cli/help/HelpCommandTest.kt
index de22a69..4179bf6 100644
--- a/src/test/java/com/android/tools/metalava/cli/help/HelpCommandTest.kt
+++ b/src/test/java/com/android/tools/metalava/cli/help/HelpCommandTest.kt
@@ -36,6 +36,7 @@
issues Provides help related to issues and issue reporting
package-filters Explains the syntax and behavior of package filters used in options like
--stub-packages.
+ signature-file-formats Describes the different signature file formats.
"""
.trimIndent()
}
@@ -71,4 +72,61 @@
.trimIndent()
}
}
+
+ @Test
+ fun `Test help signature-file-formats`() {
+ commandTest {
+ args += listOf("help", "signature-file-formats")
+
+ expectedStdout =
+ """
+Usage: metalava help signature-file-formats
+
+ Describes the different signature file formats.
+
+ See `FORMAT.md` in the top level metalava directory for more information.
+
+ Conceptually, a signature file format is a set of properties that determine the types of information that will be
+ output to the API signature file and how it is represented. A format version is simply a set of defaults for those
+ properties.
+
+ The supported properties are:
+
+ * `kotlin-style-nulls = yes|no` - if `no` then the signature file will use `@Nullable` and `@NonNull` annotations to
+ indicate that the annotated item accepts `null` and does not accept `null` respectively and neither indicates that
+ it's not defined.
+
+ If `yes` then the signature file will use a type suffix of `?`, no type suffix and a type suffix of `!` to indicate
+ the that the type accepts `null`, does not accept `null` or it's not defined respectively.
+
+ * `concise-default-values = yes|no` - if `no` then Kotlin parameters that have a default value will include that value
+ in the signature file. If `yes` then those parameters will simply be prefixed with `optional`, as if it was a keyword
+ and no value will be included.
+
+ Currently, metalava supports the following versions:
+
+ * `2.0` (--format=v2) - this is the base version (more details in `FORMAT.md`) on which all the others are based. It
+ sets the properties as follows:
+
+ + kotlin-style-nulls = no
+ + concise-default-values = no
+
+ * `3.0` (--format=v3) - this is `2.0` plus `kotlin-style-nulls = yes` giving the following properties:
+
+ + kotlin-style-nulls = yes
+ + concise-default-values = no
+
+ * `4.0` (--format=v4) - this is 3.0` plus `concise-default-values = yes` giving the following properties:
+
+ + kotlin-style-nulls = yes
+ + concise-default-values = yes
+
+ The `--api-overloaded-method-order` option also affects the contents in the signature file, i.e. whether overloaded
+ methods are sorted based on their source order or purely based on their signature. However, it is orthogonal to a
+ specific version and should be considered as purely a temporary measure, provided to aid migration and as such will be
+ removed at some time in future.
+ """
+ .trimIndent()
+ }
+ }
}
diff --git a/src/test/java/com/android/tools/metalava/cli/signature/SignatureFormatOptionsTest.kt b/src/test/java/com/android/tools/metalava/cli/signature/SignatureFormatOptionsTest.kt
index 66dca2c..5e77ca8 100644
--- a/src/test/java/com/android/tools/metalava/cli/signature/SignatureFormatOptionsTest.kt
+++ b/src/test/java/com/android/tools/metalava/cli/signature/SignatureFormatOptionsTest.kt
@@ -33,6 +33,8 @@
Options controlling the format of the generated signature files.
+ See `metalava help signature-file-formats` for more information.
+
--api-overloaded-method-order [source|signature]
Specifies the order of overloaded methods in signature files. Applies to
the contents of the files specified on --api and --removed-api.
