smalltalk-usage-finder

Smalltalk Usage Finder

Discover how Smalltalk classes, methods, and packages are used in practice through systematic analysis of documentation, examples, and real-world code.

Core Analysis Workflows

1. Understanding Class Responsibilities

Goal: Discover what a class does and its intended purpose.

Primary Tool: get_class_comment - The authoritative source for class responsibility.

Workflow:

1. Verify class name (if uncertain): search_classes_like(query)
2. Get class comment: get_class_comment(class_name)
3. Present responsibility clearly

Example:

search_classes_like("Point")
→ ["Point", "PointArray", ...]

get_class_comment("Point")
→ "I represent an x-y pair of numbers usually designating a location on the screen."

Best practice: Always start with the class comment - it's the authoritative documentation.

2. Finding Class Usage Patterns

Goal: Learn how to use a class by examining real examples.

Primary Tools: search_references_to_class, get_method_source, list_methods

Workflow:

1. Check for example methods:
   - list_methods(package) or search_methods_like("example")
   - Filter for "exampleXXX" methods (class-side)
   - get_method_source for each example

2. Find real-world usage:
   - search_references_to_class(class_name)
   - Get source for top 5-10 references
   - Identify common patterns

3. Synthesize usage guide

Example methods convention:

• Class-side methods in examples category
• Named: exampleSimple, example1, exampleWithData
• Best source for learning how to use a class

3. Finding Method Usage

Goal: Understand how a specific method is used in context.

Primary Tools: search_references, get_method_source

Challenge: Polymorphism - same method name in multiple classes.

Workflow:

1. Verify method exists: search_methods_like(method_name)
2. Find all references: search_references(method_name)
3. Filter by context:
   - Get source for each reference
   - Look for variable naming clues (e.g., "aPoint" → Point)
   - Check type comments
4. Present usage with examples

Filtering by context:

• Variable names: aPoint → Point, dict → Dictionary
• Type hints: "aPoint <Point>"
• Method category: arithmetic, accessing, etc.

4. Generating Package Overviews

Goal: Understand package structure and purpose.

Primary Tools: list_classes, get_class_comment

Workflow:

1. List all classes: list_classes(package_name)
2. Get comments for key classes (top 10-20)
3. Identify class hierarchy and relationships
4. Find entry points (constructors, main classes)
5. Generate overview

Focus on:

• Base classes and their implementations
• Main entry points
• Common usage patterns

5. Handling Ambiguous Names

Goal: Resolve unclear or partial class/method names.

Primary Tools: search_classes_like, search_methods_like

Workflow:

1. Fuzzy search: search_classes_like(partial_name)
2. If multiple matches: present options to user
3. Once identified: proceed with normal workflow

Example:

search_classes_like("Dict")
→ ["Dictionary", "IdentityDictionary", "SmallDictionary", ...]

Present options:
"Found 3 classes:
1. Dictionary - General key-value storage
2. IdentityDictionary - Identity comparison
3. SmallDictionary - Optimized for <10 elements
Which one?"

Quick Reference

MCP Tools

Class inspection:

get_class_comment('ClassName')
get_class_source('ClassName')

Method inspection:

get_method_source(class: 'ClassName' method: 'methodName' is_class_method: false)

Search tools:

search_references_to_class('ClassName')
search_references('methodName')
search_classes_like('partial')
search_methods_like('partial')

Package tools:

list_classes('PackageName')
list_methods('PackageName')

Best Practices

1. Verify Names First

Use fuzzy search when uncertain:

✅ Good: search_classes_like('Dict') → confirm → proceed ❌ Bad: Assume Dict is valid class name

2. Limit Search Results

Focus on top 5-10 most relevant:

✅ Good: Analyze top 5 references ❌ Bad: Try to analyze all 500 references

3. Prioritize Examples

Check for example methods first:

✅ Good: Search examples → if none, search references ❌ Bad: Immediately search all references

4. Trust Class Comments

They are authoritative documentation:

✅ Good: Start with get_class_comment ❌ Bad: Ignore comments, only look at code

5. Provide Context

Show surrounding code, not just isolated lines:

✅ Good: Show full method with context ❌ Bad: Show only the single line with method call

6. Handle Polymorphism

Use context clues to filter:

✅ Good: Check variable names, method category ❌ Bad: Assume first match is correct

7. Clarify Ambiguity

Ask user instead of guessing:

✅ Good: "Found 3 matches. Which one?" ❌ Bad: "Assuming you meant Stream..."

Common Pitfalls

Pitfall 1: Assuming Exact Names

Problem: User says "Point" but means "PointArray" Solution: Always verify with search_classes_like

Pitfall 2: Reference Overload

Problem: 500 search results overwhelming Solution: Limit to top 10, filter by relevance

Pitfall 3: Polymorphic Confusion

Problem: Same method in multiple classes Solution: Use variable names and context to filter

Pitfall 4: Missing Examples

Problem: Only checking instance-side Solution: Check class-side for exampleXXX methods

Pitfall 5: No Synthesis

Problem: Just showing raw search results Solution: Analyze patterns and create usage guide

Analysis Pattern Examples

Example 1: Class Usage

User: "How do I use Point?"

1. get_class_comment('Point')
   → "I represent x-y pair..."

2. search_methods_like('example')
   → Find: "Point class>>exampleGrid"

3. get_method_source (example)
   → Shows: x@y syntax

4. search_references_to_class('Point')
   → Top usages in Rectangle, Morph

5. Synthesize:
   "Point is created with @: 100@200
    Common operations: x, y, +, -, *
    Example: center := (100@100 + 200@200) // 2"

Example 2: Method Usage

User: "How to use distanceTo:?"

1. search_methods_like('distanceTo')
   → Multiple classes

2. search_references('distanceTo:')
   → Find usage examples

3. Filter by variable names:
   - "aPoint distanceTo:" → Point class
   - Context: geometric operations

4. get_method_source for Point version

5. Synthesize:
   "Point>>distanceTo: calculates distance
    Usage: point1 distanceTo: point2
    Returns: Float (Euclidean distance)"

For complete analysis techniques and detailed scenarios, see:

• Usage Analysis Reference - Comprehensive analysis techniques
• Usage Scenarios - Real-world analysis examples

Summary

Key workflow: Verify → Search → Inspect → Filter → Synthesize → Present

Analysis priorities:

1. Start with class comments (authoritative)
2. Look for example methods (best learning resource)
3. Limit search results (top 5-10)
4. Provide context (surrounding code)
5. Synthesize findings (don't dump raw data)

Remember: The goal is understanding HOW to use code, not explaining implementation details.