From 390d7e27ed6043de4906d6171fe851cae3901b0e Mon Sep 17 00:00:00 2001
From: Chenhao Zuo <nero@meta.com>
Date: Wed, 29 Jan 2025 18:20:07 -0800
Subject: [PATCH] Add docs for UnconfiguredTargetSet/ConfiguredTargetSet

Summary: Add docs for UnconfiguredTargetSet/ConfiguredTargetSet

Reviewed By: scottcao

Differential Revision: D68848317

fbshipit-source-id: 7f9f34f059d4a2b030ce1449c65b299009045617
---
 .../src/bxl/starlark_defs/targetset.rs        | 53 +++++++++++++++++++
 .../bxl/ConfiguredTargetSet.md                |  6 +++
 .../bxl/UnconfiguredTargetSet.md              |  6 +++
 3 files changed, 65 insertions(+)

diff --git a/app/buck2_bxl/src/bxl/starlark_defs/targetset.rs b/app/buck2_bxl/src/bxl/starlark_defs/targetset.rs
index dbbf1daf5833..ff123a993d52 100644
--- a/app/buck2_bxl/src/bxl/starlark_defs/targetset.rs
+++ b/app/buck2_bxl/src/bxl/starlark_defs/targetset.rs
@@ -16,6 +16,10 @@ use buck2_query::query::syntax::simple::eval::set::TargetSet;
 use derive_more::Display;
 use dupe::Dupe;
 use starlark::any::ProvidesStaticType;
+use starlark::environment::Methods;
+use starlark::environment::MethodsBuilder;
+use starlark::environment::MethodsStatic;
+use starlark::starlark_module;
 use starlark::typing::Ty;
 use starlark::values::starlark_value;
 use starlark::values::type_repr::StarlarkTypeRepr;
@@ -89,6 +93,11 @@ impl<'v, Node: NodeLike> AllocValue<'v> for StarlarkTargetSet<Node> {
 impl<'v, Node: NodeLike> StarlarkValue<'v> for StarlarkTargetSet<Node> {
     type Canonical = Self;
 
+    fn get_methods() -> Option<&'static Methods> {
+        static RES: MethodsStatic = MethodsStatic::new();
+        RES.methods(starlark_target_set_methods)
+    }
+
     fn iterate_collect(&self, heap: &'v Heap) -> starlark::Result<Vec<Value<'v>>> {
         Ok(self.iter(heap).collect())
     }
@@ -163,3 +172,47 @@ impl<Node: NodeLike> StarlarkTargetSet<Node> {
         ValueLike::downcast_ref::<Self>(x)
     }
 }
+
+/// A set-like object for managing buck2 target nodes.
+/// It can be either `ConfiguredTargetSet` or `UnConfiguredTargetSet` where contains either [`ConfiguredTargetNode`](../ConfiguredTargetNode) or [`UnconfiguredTargetNode`](../UnconfiguredTargetNode) respectively.
+///
+/// It provides common set operations for target nodes.
+/// It supports iteration, indexing, addition (union), subtraction (difference), equality comparison, and intersection operations.
+///
+/// Operations:
+/// * `+`  : Union of two TargetSets
+/// * `-`  : Difference between two TargetSets
+/// * `==` : Equality comparison
+/// * `&` : Intersection of two TargetSets
+/// * `[]` : Index access
+/// * `len()`: Number of targets in set
+/// * `iter()`: Iteration over targets
+/// * constructor: [`bxl.ctarget_set()`](../#ctarget_set) for `ConfiguredTargetSet` and [`bxl.utarget_set()`](../#utarget_set) for `UnconfiguredTargetSet`
+///
+/// Example:
+/// ```python
+/// # Combine sets
+/// all_targets = targets1 + targets2  # Union
+///
+/// # Remove targets
+/// remaining = targets1 - targets2    # Difference
+///
+/// # Check if sets are equal
+/// if targets1 == targets2:
+///     print("Sets contain same targets")
+///
+/// # Iterate through targets
+/// for target in targets1:
+///    print(target)
+///
+///  # Get target by index
+/// first_target = targets1[0]
+///
+/// # Get number of targets
+/// count = len(targets1)
+///
+/// # Intersection of sets
+/// common = targets1 & targets2
+/// ```
+#[starlark_module]
+fn starlark_target_set_methods(builder: &mut MethodsBuilder) {}
diff --git a/tests/core/docs/test_builtin_docs_data/buck2-golden-docs/bxl/ConfiguredTargetSet.md b/tests/core/docs/test_builtin_docs_data/buck2-golden-docs/bxl/ConfiguredTargetSet.md
index 95637b478299..4eda67923e07 100644
--- a/tests/core/docs/test_builtin_docs_data/buck2-golden-docs/bxl/ConfiguredTargetSet.md
+++ b/tests/core/docs/test_builtin_docs_data/buck2-golden-docs/bxl/ConfiguredTargetSet.md
@@ -1,3 +1,9 @@
 # This file is @generated, regenerate by re-running test with `-- --env BUCK2_UPDATE_GOLDEN=1` appended to the test command
 
 # ConfiguredTargetSet
+# Combine sets
+# Remove targets
+# Check if sets are equal
+# Iterate through targets
+# Get number of targets
+# Intersection of sets
diff --git a/tests/core/docs/test_builtin_docs_data/buck2-golden-docs/bxl/UnconfiguredTargetSet.md b/tests/core/docs/test_builtin_docs_data/buck2-golden-docs/bxl/UnconfiguredTargetSet.md
index 143ed677a14a..4498cf8a4b73 100644
--- a/tests/core/docs/test_builtin_docs_data/buck2-golden-docs/bxl/UnconfiguredTargetSet.md
+++ b/tests/core/docs/test_builtin_docs_data/buck2-golden-docs/bxl/UnconfiguredTargetSet.md
@@ -1,3 +1,9 @@
 # This file is @generated, regenerate by re-running test with `-- --env BUCK2_UPDATE_GOLDEN=1` appended to the test command
 
 # UnconfiguredTargetSet
+# Combine sets
+# Remove targets
+# Check if sets are equal
+# Iterate through targets
+# Get number of targets
+# Intersection of sets