Revise LANGUAGE_SUPPORT.md for clarity and updates

Updated the language support documentation to include additional notes and clarifications for each supported language. Revised the structure and formatting for consistency and clarity.

Author: jgravelle

LANGUAGE_SUPPORT.md

@@ -2,79 +2,89 @@
 
 ## Supported Languages
 
-| Language | Extensions | Parser | Symbol Types | Decorators | Docstrings | Known Limitations |
-|----------|-----------|--------|-------------|-----------|-----------|-------------------|
-| Python | `.py` | tree-sitter-python | function, class, method, constant, type | `@decorator` | Triple-quoted strings | Type alias requires Python 3.12+ syntax |
-| JavaScript | `.js`, `.jsx` | tree-sitter-javascript | function, class, method, constant | None | `//` / `/** */` comments | Arrow functions without names skipped |
-| TypeScript | `.ts`, `.tsx` | tree-sitter-typescript | function, class, method, constant, type | `@decorator` | `//` / `/** */` comments | Decorators require TC39 stage 3+ |
-| Go | `.go` | tree-sitter-go | function, method, type, constant | None | `//` comments | No class-like nesting |
-| Rust | `.rs` | tree-sitter-rust | function, type (struct/enum/trait), class (impl), constant | `#[attr]` | `///` / `//!` comments | Macro-generated items invisible |
-| Java | `.java` | tree-sitter-java | method, class, type (interface/enum), constant | `@Annotation` | `/** */` Javadoc | Inner classes have limited nesting |
+| Language   | Extensions    | Parser                 | Symbol Types                                       | Decorators    | Docstrings                 | Notes / Limitations                                              |
+| ---------- | ------------- | ---------------------- | -------------------------------------------------- | ------------- | -------------------------- | ---------------------------------------------------------------- |
+| Python     | `.py`         | tree-sitter-python     | function, class, method, constant, type            | `@decorator`  | Triple-quoted strings      | Type aliases require Python 3.12+ syntax for full fidelity       |
+| JavaScript | `.js`, `.jsx` | tree-sitter-javascript | function, class, method, constant                  | —             | `//` and `/** */` comments | Anonymous arrow functions without assigned names are not indexed |
+| TypeScript | `.ts`, `.tsx` | tree-sitter-typescript | function, class, method, constant, type            | `@decorator`  | `//` and `/** */` comments | Decorator extraction depends on Stage-3 decorator syntax         |
+| Go         | `.go`         | tree-sitter-go         | function, method, type, constant                   | —             | `//` comments              | No class hierarchy (language limitation)                         |
+| Rust       | `.rs`         | tree-sitter-rust       | function, type (struct/enum/trait), impl, constant | `#[attr]`     | `///` and `//!` comments   | Macro-generated symbols are not visible to the parser            |
+| Java       | `.java`       | tree-sitter-java       | method, class, type (interface/enum), constant     | `@Annotation` | `/** */` Javadoc           | Deep inner-class nesting may be flattened                        |
 
-## Parser: tree-sitter
+---
 
-All parsing uses [tree-sitter](https://tree-sitter.github.io/) via the `tree-sitter-language-pack` Python package. This provides:
+## Parser Engine
 
-- Incremental, error-tolerant parsing
-- Consistent AST representation across languages
-- Pre-compiled bindings for all 6 languages
+All language parsing is powered by **tree-sitter** via the `tree-sitter-language-pack` Python package, providing:
+
+* Incremental, error-tolerant parsing
+* Uniform AST representation across languages
+* Pre-compiled grammars for supported languages
 
 **Dependency:** `tree-sitter-language-pack>=0.7.0` (pinned in `pyproject.toml`)
 
+---
+
 ## Adding a New Language
 
-1. **Create a `LanguageSpec`** in `src/jcodemunch_mcp/parser/languages.py`:
+1. **Define a `LanguageSpec`** in `src/jcodemunch_mcp/parser/languages.py`:
 
 ```python
 NEW_LANG_SPEC = LanguageSpec(
-    ts_language="new_language",           # tree-sitter grammar name
-    symbol_node_types={                    # AST node type -> symbol kind
+    ts_language="new_language",
+    symbol_node_types={
         "function_definition": "function",
         "class_definition": "class",
     },
-    name_fields={                          # How to extract names
+    name_fields={
         "function_definition": "name",
         "class_definition": "name",
     },
-    param_fields={                         # Parameter extraction
+    param_fields={
         "function_definition": "parameters",
     },
-    return_type_fields={},                 # Return type extraction
-    docstring_strategy="preceding_comment", # or "next_sibling_string"
-    decorator_node_type=None,              # Decorator node type if any
-    container_node_types=["class_definition"],  # Nesting containers
-    constant_patterns=[],                  # Constant node types
-    type_patterns=[],                      # Type definition node types
+    return_type_fields={},
+    docstring_strategy="preceding_comment",
+    decorator_node_type=None,
+    container_node_types=["class_definition"],
+    constant_patterns=[],
+    type_patterns=[],
 )
 ```
 
-2. **Register it** in `LANGUAGE_REGISTRY`:
+2. **Register the language**:
+
 ```python
 LANGUAGE_REGISTRY["new_language"] = NEW_LANG_SPEC
 ```
 
-3. **Add file extensions** to `LANGUAGE_EXTENSIONS`:
+3. **Map file extensions**:
+
 ```python
 LANGUAGE_EXTENSIONS[".ext"] = "new_language"
 ```
 
-4. **Verify** the tree-sitter grammar name exists in `tree-sitter-language-pack`:
+4. **Verify parser availability**:
+
 ```python
 from tree_sitter_language_pack import get_parser
-parser = get_parser("new_language")  # Must not raise
+get_parser("new_language")  # Must not raise
 ```
 
-5. **Write tests** in `tests/test_parser.py`:
+5. **Add parser tests**:
+
 ```python
 def test_parse_new_language():
-    source = "..."  # Minimal source with function + class
+    source = "..."
     symbols = parse_file(source, "test.ext", "new_language")
     assert len(symbols) >= 2
 ```
 
-## Debugging AST Node Types
+---
+
+## Inspecting AST Node Types
 
-To inspect what tree-sitter produces for a given source file:
+To inspect the node types produced by tree-sitter for a source file:
 
 ```python
 from tree_sitter_language_pack import get_parser
@@ -90,4 +100,4 @@ def print_tree(node, indent=0):
 print_tree(tree.root_node)
 ```
 
-This helps identify the correct `symbol_node_types` and `name_fields` for a new language.
+This inspection process helps identify the correct `symbol_node_types`, `name_fields`, and extraction rules when adding support for a new language.