API-LINT.md

# API Lint

Metalava can optionally run warn about various API problems based on the Android
API Council's guidelines, described in go/android-api-guidelines.

These rules are not always exact. For example, you should avoid using acronyms
in names; e.g. a method should be named handleUri, not handleURI. But what about
getZOrder?  This is probably better than getZorder, but metalava can't tell
without consulting a dictionary.

Therefore, there are cases where you want to say "ok, that's good advice in
general, but wrong here". In order to avoid having this warningshow up again
and again, there are two ways to mark an issue such that it is no longer
flagged.

(Note that metalava will not report issues on classes, methods and fields that
are deprecated since these are presumably already known to be bad and are already
discouraged.)

## Suppressing with @Suppress

Next to an error message, metalava will include the issue id. For example,
here's a sample error message:

    src/android/pkg/MyStringImpl.java:3: error: Don't expose your implementation details: MyStringImpl ends with Impl [EndsWithImpl]

Here the id is "EndsWithImpl". You can suppress this with the @SuppressLint
annotation:

    ...
    import android.annotation.SuppressLint;
    ...

    @SuppressLint("EndsWithImpl")
    public class MyStringImpl {
        ...

## Suppressing with baselines

Metalava also has support for "baselines", which are files which record all the
current warnings and errors in the codebase. When metalava runs, it looks up the
baseline to see if a given issue is already listed in the baseline, and if so,
it is silently ignored.

You can pass a flag to metalava ("--update-baseline") to tell it to update the
baseline files with any new errors it comes across instead of reporting
them. With soong, if you specify the baseline explicitly, like this:

    --- a/Android.bp
    +++ b/Android.bp
    @@ -1678,6 +1678,7 @@ droidstubs {
         },
         api_lint: {
             enabled: true,
        ==>  baseline_filename: "api/baseline.txt", <==
         }
         jdiff_enabled: true,
     }

then the build system will automatically supply `--update-baseline` on your
behalf to a generated file in the out/ folder, and if there's a failure metalava
will tell you where to find the updated baseline which you can then copy into
place:

    ...
    93 new API lint issues were found. See tools/metalava/API-LINT.md for how to handle these.
    ************************************************************
    Your API changes are triggering API Lint warnings or errors.
    To make these errors go away, you have two choices:

    1. You can suppress the errors with @SuppressLint("<id>")
    2. You can update the baseline by executing the following
       command:
           cp \
           out/soong/.intermediates/frameworks/base/system-api-stubs-docs/android_common/api/system-baseline.txt \
           frameworks/base/api/system-baseline.txt
       To submit the revised baseline.txt to the main Android
       repository, you will need approval.
    ************************************************************



Then re-run the build and you should now see diffs to the baseline file; git
diff to make sure you're really only marking the issues you intended to include.

    $ git status
    ...
    Untracked files:
      (use "git add <file>..." to include in what will be committed)

          baseline.txt

## Copying File Manually

In the near future the build system will not allow source files to be modified
by the build. At that point you'll need to manually copy in the file instead.
During the build, before failing, metalava will emit a message like this:

    ...
    metalava wrote updated baseline to out/something/baseline.txt
    ...

At that point you can copy the file to where you need:

```sh
$ cp out/something/baseline.txt frameworks/base/api/baseline.txt
```

## Existing Issues

You can view the exact set of existing issues (current APIs that get flagged by
API lint) by inspecting the baseline files in the source tree, but to get a
sense of the types of issues that are more likely to have a false positive,
here's the existing distribution as of early 2019:

    Count Issue Id                       Rule Severity
    --------------------------------------------------

      932 ProtectedMember                M7   error
      321 OnNameExpected                      warning
      288 ArrayReturn                         warning
      269 ActionValue                    C4   error
      266 NoByteOrShort                  FW12 warning
      221 ExecutorRegistration           L1   warning
      211 AllUpper                       C2   error
      206 GetterSetterNames              M6   error
      185 BannedThrow                         error
      172 SamShouldBeLast                     warning
      159 NoClone                             error
      159 ParcelNotFinal                 FW8  error
      119 NotCloseable                        warning
      105 ListenerLast                   M3   warning
       81 ConcreteCollection             CL2  error
       78 StaticUtils                         error
       76 IntentName                     C3   error
       74 VisiblySynchronized            M5   error
       72 GenericException               S1   error
       65 KotlinOperator                      warning
       57 AcronymName                    S1   warning
       55 ParcelCreator                  FW3  error
       54 ParcelConstructor              FW3  error
       53 UseIcu                              warning
       48 Enum                           F5   error
       41 RethrowRemoteException         FW9  error
       37 AutoBoxing                     M11  error
       35 StreamFiles                    M10  warning
       28 IntentBuilderName              FW1  warning
       27 ServiceName                    C4   error
       26 ListenerInterface              L1   error
       25 ContextFirst                   M3   error
       25 InterfaceConstant              C4   error
       24 CallbackInterface              CL3  error
       24 RegistrationName               L3   error
       23 IllegalStateException          S1   warning
       22 EqualsAndHashCode              M8   error
       22 PackageLayering                FW6  warning
       18 MinMaxConstant                 C8   warning
       18 SingletonConstructor                error
       17 MethodNameUnits                     error
       15 MissingBuildMethod                  warning
       15 UserHandleName                      warning
       14 UserHandle                          warning
       13 ResourceFieldName                   error
       12 ManagerLookup                       error
       11 ManagerConstructor                  error
        9 CallbackMethodName             L1   error
        9 ParcelableList                      warning
        8 CallbackName                   L1   warning
        7 HeavyBitSet                         error
        7 ResourceValueFieldName         C7   error
        6 CompileTimeConstant                 error
        6 SetterReturnsThis              M4   warning
        4 EndsWithImpl                        error
        4 TopLevelBuilder                     warning
        4 UseParcelFileDescriptor        FW11 error
        3 MentionsGoogle                      error
        3 StartWithLower                 S1   error
        2 AbstractInner                       warning
        2 BuilderSetStyle                     warning
        2 OverlappingConstants           C1   warning
        2 PairedRegistration             L2   error
        2 SingularCallback               L1   error
        2 StartWithUpper                 S1   error
        1 ContextNameSuffix              C4   error
        1 KotlinKeyword                       error
    --------------------------------------------------
     4902

(This is generated when metalava is invoked with both --verbose and --update-baseline.)