docs: move implementation details from docstrings to block comments

Author: shuoweil

bigframes/display/_flatten.py

@@ -89,13 +89,6 @@ def flatten_nested_data(
 ) -> FlattenResult:
     """Flatten nested STRUCT and ARRAY columns for display.
 
-    This function coordinates the flattening process:
-    1.  Classifies columns into STRUCT, ARRAY, ARRAY-of-STRUCT, and standard types.
-    2.  Flattens ARRAY-of-STRUCT columns into multiple ARRAY columns (one per struct field).
-        This simplifies the subsequent explosion step.
-    3.  Flattens top-level STRUCT columns into separate columns.
-    4.  Explodes all ARRAY columns (original and those from step 2) into multiple rows.
-
     Args:
         dataframe: The input DataFrame containing potential nested structures.
 
@@ -111,6 +104,12 @@ def flatten_nested_data(
             nested_columns=set(),
         )
 
+    # Coordinates the flattening process:
+    # 1. Classifies columns into STRUCT, ARRAY, ARRAY-of-STRUCT, and standard types.
+    # 2. Flattens ARRAY-of-STRUCT columns into multiple ARRAY columns (one per struct field).
+    #    This simplifies the subsequent explosion step.
+    # 3. Flattens top-level STRUCT columns into separate columns.
+    # 4. Explodes all ARRAY columns (original and those from step 2) into multiple rows.
     result_df = dataframe.copy()
 
     classification = _classify_columns(result_df)
@@ -156,15 +155,14 @@ def _classify_columns(
 ) -> ColumnClassification:
     """Identify all STRUCT and ARRAY columns in the DataFrame.
 
-    It inspects the PyArrow dtype of each column to determine if it is a
-    STRUCT, LIST (Array), or LIST of STRUCTs.
-
     Args:
         dataframe: The DataFrame to inspect.
 
     Returns:
         A ColumnClassification object containing lists of column names for each category.
     """
+    # Inspects the PyArrow dtype of each column to determine if it is a
+    # STRUCT, LIST (Array), or LIST of STRUCTs.
     initial_columns = list(dataframe.columns)
     struct_columns: list[str] = []
     array_columns: list[str] = []
@@ -283,13 +281,6 @@ def _explode_array_columns(
     It handles multiple array columns by ensuring they are exploded in sync
     relative to the other columns.
 
-    Design details:
-    - We group by all non-array columns to maintain context.
-    - `_row_num` is used to track the index within the exploded array, effectively
-       synchronizing multiple arrays if they belong to the same row.
-    - Continuation rows (index > 0 in the explosion) are tracked so we can clear
-      repeated values in the display.
-
     Args:
         dataframe: The DataFrame to explode.
         array_columns: List of array columns to explode.
@@ -300,6 +291,12 @@ def _explode_array_columns(
     if not array_columns:
         return ExplodeResult(dataframe, [], set())
 
+    # Implementation details:
+    # - We group by all non-array columns to maintain context.
+    # - `_row_num` is used to track the index within the exploded array, effectively
+    #    synchronizing multiple arrays if they belong to the same row.
+    # - Continuation rows (index > 0 in the explosion) are tracked so we can clear
+    #   repeated values in the display.
     original_cols = dataframe.columns.tolist()
     work_df = dataframe