Improve Faust doc API retrieval and notes extraction

Author: sletz

README.md

@@ -58,6 +58,7 @@ extracts for each documented symbol:
 - `summary`
 - `usage`
 - `params`
+- `notes`
 - `io` with `inSignals` / `outSignals` when derivable
 - `testCode`
 - `references`

scripts/build_faust_doc_index.py

@@ -343,6 +343,8 @@ def parse_doc_body(body_lines: Iterable[str]) -> dict[str, object]:
     - free text before any subsection -> summary
     - `#### Usage` -> usage string or fenced usage block
     - `Where:` -> list of documented parameters
+    - general notes that appear inside `Where:` after the parameter bullets
+      -> `notes`
     - `#### Test` -> example snippet
     - `#### Reference` / `#### References` -> references list
 
@@ -353,13 +355,20 @@ def parse_doc_body(body_lines: Iterable[str]) -> dict[str, object]:
     summary_lines: list[str] = []
     usage_buffer: list[str] = []
     params: list[dict[str, str]] = []
+    notes: list[str] = []
     references: list[str] = []
     test_code: str | None = None
 
     section = "summary"
     in_fence = False
     fence_buffer: list[str] = []
     current_param: dict[str, str] | None = None
+    current_note_index: int | None = None
+
+    def is_general_note_line(text: str) -> bool:
+        """Heuristically detect note-like prose inside a `Where:` section."""
+
+        return bool(re.match(r"^(note|notes|output|outputs|return|returns|result|results)\b", text, flags=re.IGNORECASE))
 
     def flush_fence() -> None:
         """Commit the current fenced code block into the active logical section."""
@@ -397,6 +406,7 @@ def flush_fence() -> None:
         if re.match(r"^where\s*:?\s*$", trimmed, flags=re.IGNORECASE):
             section = "where"
             current_param = None
+            current_note_index = None
             continue
 
         if trimmed.startswith("```"):
@@ -426,8 +436,15 @@ def flush_fence() -> None:
             if match:
                 current_param = {"name": match.group(1).strip(), "description": match.group(2).strip()}
                 params.append(current_param)
-            elif current_param and trimmed and not trimmed.startswith("* "):
+                current_note_index = None
+            elif current_note_index is not None and trimmed and not trimmed.startswith("* "):
+                notes[current_note_index] = f"{notes[current_note_index]} {trimmed}".strip()
+            elif current_param and trimmed and not trimmed.startswith("* ") and not is_general_note_line(trimmed):
                 current_param["description"] = f"{current_param['description']} {trimmed}".strip()
+            elif trimmed and not trimmed.startswith("* "):
+                notes.append(trimmed)
+                current_note_index = len(notes) - 1
+                current_param = None
             continue
 
         if section == "reference":
@@ -440,12 +457,16 @@ def flush_fence() -> None:
 
     usage = None
     if usage_buffer:
-        usage = next((line for line in usage_buffer if ":" in line), usage_buffer[0])
+        if len(usage_buffer) == 1:
+            usage = usage_buffer[0]
+        else:
+            usage = re.sub(r"\s+", " ", " ".join(usage_buffer)).strip()
 
     return {
         "summary": " ".join(summary_lines).strip(),
         "usage": usage,
         "params": params,
+        "notes": notes,
         "testCode": test_code,
         "references": references,
     }
@@ -569,6 +590,7 @@ def build_index(repo_root: Path, stdlib: Path) -> dict[str, object]:
                 "summary": body["summary"],
                 "usage": usage,
                 "params": body["params"],
+                "notes": body["notes"],
                 "io": io,
                 "testCode": body["testCode"],
                 "references": body["references"],
@@ -616,6 +638,7 @@ def make_symbol_summary(symbol: dict[str, object]) -> dict[str, object]:
         "tags": symbol["tags"],
         "source": symbol["source"],
         "hasTestCode": bool(symbol.get("testCode")),
+        "notesCount": len(symbol.get("notes", [])),
         "referencesCount": len(symbol.get("references", [])),
     }
 

scripts/faust_doc_api.py

@@ -299,6 +299,23 @@ def get_faust_examples(store: FaustDocStore, symbol_or_module: str, limit: int =
     if not key:
         raise ValueError("Missing symbolOrModule")
 
+    library, symbols = store.get_library_symbols(key)
+    if library is not None:
+        examples = []
+        for symbol in symbols:
+            if not symbol.get("testCode"):
+                continue
+            examples.append(
+                {
+                    "symbol": symbol.get("qualifiedName"),
+                    "code": symbol.get("testCode"),
+                    "source": symbol.get("source"),
+                }
+            )
+            if len(examples) >= limit:
+                break
+        return {"scope": "module", "query": key, "file": library.get("file"), "examples": examples}
+
     found, _ = store.find_symbol(key)
     if found is not None:
         examples = []
@@ -312,24 +329,7 @@ def get_faust_examples(store: FaustDocStore, symbol_or_module: str, limit: int =
             )
         return {"scope": "symbol", "query": key, "examples": examples}
 
-    library, symbols = store.get_library_symbols(key)
-    if library is None:
-        raise ValueError(f"No symbol/module found: {key}")
-
-    examples = []
-    for symbol in symbols:
-        if not symbol.get("testCode"):
-            continue
-        examples.append(
-            {
-                "symbol": symbol.get("qualifiedName"),
-                "code": symbol.get("testCode"),
-                "source": symbol.get("source"),
-            }
-        )
-        if len(examples) >= limit:
-            break
-    return {"scope": "module", "query": key, "file": library.get("file"), "examples": examples}
+    raise ValueError(f"No symbol/module found: {key}")
 
 
 def explain_faust_symbol_for_goal(store: FaustDocStore, symbol: str, goal: str) -> dict[str, object]:
@@ -341,23 +341,28 @@ def explain_faust_symbol_for_goal(store: FaustDocStore, symbol: str, goal: str)
 
     goal_text = str(goal or "").strip()
     params = found.get("params", [])
+    notes = found.get("notes", [])
     param_hint = (
         "Key params: " + "; ".join(f"{param['name']} ({param['description']})" for param in params)
         if params
         else "No explicit parameter notes found."
     )
+    notes_hint = "Notes: " + " ".join(str(note) for note in notes) if notes else None
     usage = f"Usage: {found['usage']}" if found.get("usage") else "Usage not documented."
-    recommendation = " ".join(
-        [
-            f"Use {found['qualifiedName']} when it matches this goal: {goal_text or 'general DSP design'}.",
-            str(found.get("summary") or "No summary found in comments."),
-            usage,
-            param_hint,
-            "A test snippet is available via get_faust_examples."
-            if found.get("testCode")
-            else "No test snippet found.",
-        ]
+    parts = [
+        f"Use {found['qualifiedName']} when it matches this goal: {goal_text or 'general DSP design'}.",
+        str(found.get("summary") or "No summary found in comments."),
+        usage,
+        param_hint,
+    ]
+    if notes_hint:
+        parts.append(notes_hint)
+    parts.append(
+        "A test snippet is available via get_faust_examples."
+        if found.get("testCode")
+        else "No test snippet found."
     )
+    recommendation = " ".join(parts)
     return {"symbol": found.get("qualifiedName"), "goal": goal_text, "recommendation": recommendation}