From a173320627d85e0245f89632604bdbdc9cd91aea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ezgi=20=C3=87i=C3=A7ek?= Date: Thu, 18 Jun 2020 04:23:22 -0700 Subject: [PATCH] [doc] Add documentation for litho required props Reviewed By: jvillard Differential Revision: D22091194 fbshipit-source-id: f049bea0d --- .../checkers/LithoRequiredProps.md | 51 +++++++++++++++++++ infer/man/man1/infer-analyze.txt | 2 +- infer/man/man1/infer-full.txt | 2 +- infer/man/man1/infer.txt | 2 +- infer/src/base/Checker.ml | 7 ++- infer/src/base/IssueType.ml | 3 +- 6 files changed, 61 insertions(+), 6 deletions(-) create mode 100644 infer/documentation/checkers/LithoRequiredProps.md diff --git a/infer/documentation/checkers/LithoRequiredProps.md b/infer/documentation/checkers/LithoRequiredProps.md new file mode 100644 index 000000000..5e69b0add --- /dev/null +++ b/infer/documentation/checkers/LithoRequiredProps.md @@ -0,0 +1,51 @@ +This analysis checks that all non-optional [`@Prop`](https://fblitho.com/docs/props)`s have been specified when constructing Litho components. This is a [Litho](https://fblitho.com/) specific checker. + + +## What are required Props? +In a nutshell, a Litho Component is essentially a class that defines immutable inputs, called prop (annotated with `@Prop`) in component hierarchy methods. For each Component there is a corresponding spec class which defines the required props:. E.g: + +```java +class MyComponentSpec { + + static void onCreate( + ComponentContext c, + @Prop(optional = true) String prop1, @Prop int prop2) { + ... + } + ... +} +``` + +`MyComponentSpec` defines two props: a String prop called `prop1` and an int prop named `prop2`. For each prop defined on the spec, the annotation processor creates a builder pattern method that has the same name as the prop. + +Developers pass down values for these props by calling the appropriate methods: + +```java +MyComponent.create(c) + .prop1("My prop 1") + .prop2(256) + .build(); +``` + +If the required props are not called, then annotation processor throws an exception in run time. This is really bad and that's where this checker comes into play to detect such cases statically. + + +## Examples + +E.g. the following is caught as [MISSING_REQUIRED_PROP](/docs/next/all-issue-types#missing_required_prop) `prop2`. + +```java +MyComponent.create(c) + .prop1("My prop 1") + .build(); +``` + +The following is ok though since `prop1` is optional. + +```java +MyComponent.create(c) + .prop2(8) + .build(); +``` + +Note that, the functions `create()` and `build()` could be defined in different methods and there could be various function calls, aliasing, and control flow patterns in between. Hence, this checker is inter-procedural. diff --git a/infer/man/man1/infer-analyze.txt b/infer/man/man1/infer-analyze.txt index 3d1cc13a1..b1b133aab 100644 --- a/infer/man/man1/infer-analyze.txt +++ b/infer/man/man1/infer-analyze.txt @@ -185,7 +185,7 @@ OPTIONS --litho-required-props Activates: checker litho-required-props: Checks that all - non-option `@Prop`s have been specified when constructing Litho + non-optional `@Prop`s have been specified when constructing Litho components. (Conversely: --no-litho-required-props) --litho-required-props-only diff --git a/infer/man/man1/infer-full.txt b/infer/man/man1/infer-full.txt index 7fcaebbec..0d85fe1e1 100644 --- a/infer/man/man1/infer-full.txt +++ b/infer/man/man1/infer-full.txt @@ -764,7 +764,7 @@ OPTIONS --litho-required-props Activates: checker litho-required-props: Checks that all - non-option `@Prop`s have been specified when constructing Litho + non-optional `@Prop`s have been specified when constructing Litho components. (Conversely: --no-litho-required-props) See also infer-analyze(1). diff --git a/infer/man/man1/infer.txt b/infer/man/man1/infer.txt index 8189e6741..79a09c63c 100644 --- a/infer/man/man1/infer.txt +++ b/infer/man/man1/infer.txt @@ -764,7 +764,7 @@ OPTIONS --litho-required-props Activates: checker litho-required-props: Checks that all - non-option `@Prop`s have been specified when constructing Litho + non-optional `@Prop`s have been specified when constructing Litho components. (Conversely: --no-litho-required-props) See also infer-analyze(1). diff --git a/infer/src/base/Checker.ml b/infer/src/base/Checker.ml index e15c0670e..c3c1da7e0 100644 --- a/infer/src/base/Checker.ml +++ b/infer/src/base/Checker.ml @@ -220,10 +220,13 @@ let config_unsafe checker = ; activates= [] } | LithoRequiredProps -> { id= "litho-required-props" - ; kind= UserFacing {title= "Litho \"Required Props\""; markdown_body= ""} + ; kind= + UserFacing + { title= "Litho \"Required Props\"" + ; markdown_body= [%blob "../../documentation/checkers/LithoRequiredProps.md"] } ; support= supports_java ; short_documentation= - "Checks that all non-option `@Prop`s have been specified when constructing Litho \ + "Checks that all non-optional `@Prop`s have been specified when constructing Litho \ components." ; cli_flags= Some {deprecated= []; show_in_help= true} ; enabled_by_default= false diff --git a/infer/src/base/IssueType.ml b/infer/src/base/IssueType.ml index 4ecd1775c..ca67c43ff 100644 --- a/infer/src/base/IssueType.ml +++ b/infer/src/base/IssueType.ml @@ -755,7 +755,8 @@ let missing_fld = let missing_required_prop = - register_from_string ~id:"MISSING_REQUIRED_PROP" Error LithoRequiredProps + register_from_string ~id:"MISSING_REQUIRED_PROP" ~hum:"Missing Required Prop" Error + LithoRequiredProps ~user_documentation:"As explained by the analysis." let mixed_self_weakself =