From 325b99cc2943d311bddf2eb381f3625236b4266b Mon Sep 17 00:00:00 2001
From: Ilya Zorin <izorin@meta.com>
Date: Mon, 4 Nov 2024 08:35:42 -0800
Subject: [PATCH] [hack][builder pattern] Add issue description for
 PULSE_UNFINISHED_BUILDER

Summary: Add issue description for PULSE_UNFINISHED_BUILDER

Reviewed By: davidpichardie

Differential Revision:
D65419581

Privacy Context Container: L1208441

fbshipit-source-id: f2159cbf64c599ac5dadd591240a52868df0d3f0
---
 .../issues/PULSE_UNFINISHED_BUILDER.md        | 34 +++++++++++++++++++
 infer/src/base/IssueType.ml                   |  3 +-
 2 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 infer/documentation/issues/PULSE_UNFINISHED_BUILDER.md

diff --git a/infer/documentation/issues/PULSE_UNFINISHED_BUILDER.md b/infer/documentation/issues/PULSE_UNFINISHED_BUILDER.md
new file mode 100644
index 0000000000..7ec37a51ca
--- /dev/null
+++ b/infer/documentation/issues/PULSE_UNFINISHED_BUILDER.md
@@ -0,0 +1,34 @@
+Classes adhering to builder pattern are usually expected to call a finalizer function at some point to produce final result based on values that were passed to a builder itself. If finalizer function hasn't been called then builder's data won't be consumed in any meaningful way and will just be discarded.
+
+```hack
+class MyBuilder {
+  private int $a = 0;
+  private int $b = 0;
+
+  public function setA(int $a): MyBuilder {
+    $this->a = $a;
+    return $this;
+  }
+
+  public function setB(int $b): MyBuilder {
+    $this->b = $b;
+    return $this;
+  }
+
+  public function saveX(): Awaitable<void> {
+    // typically do something involving IO
+  }
+}
+
+class BuilderTester {
+  public static function builderUserOK(): void {
+    $b = new MyBuilder(0);
+    $b->setA(42)->setB(97)->saveX();
+  }
+
+  public static function builderUserBad(): void {
+    $b = new MyBuilder(0);
+    $b->setA(42)->setB(97); // ERROR: saveX hasn't been called so the builder's data is discarded
+  }
+}
+```
diff --git a/infer/src/base/IssueType.ml b/infer/src/base/IssueType.ml
index e4196f60eb..dcb461c1cb 100644
--- a/infer/src/base/IssueType.ml
+++ b/infer/src/base/IssueType.ml
@@ -879,7 +879,8 @@ let pulse_unawaited_awaitable =
 
 let pulse_unfinished_builder =
   register ~enabled:false ~category:ResourceLeak ~id:"PULSE_UNFINISHED_BUILDER" Error Pulse
-    ~hum:"Unfinished Builder" ~user_documentation:"See [RESOURCE_LEAK](#resource_leak)"
+    ~hum:"Unfinished Builder"
+    ~user_documentation:[%blob "./documentation/issues/PULSE_UNFINISHED_BUILDER.md"]
 
 
 let pulse_uninitialized_const =