Skip to content

Conversation

@Crypties
Copy link

No description provided.

Created extensive documentation for Microsoft engineers working on Roslyn:

- README.md: Overview and navigation guide
- 01-repository-structure.md: Complete repository directory map
- 02-component-guide.md: Detailed component and API reference
- 03-feature-location-guide.md: Quick reference for finding features
- 04-architecture.md: Architecture patterns and design principles
- 05-developer-guide.md: Practical guide for common development tasks

This documentation maps the entire Roslyn codebase, showing exactly where
to find and modify components, features, and functionality. It provides:

- Complete directory structure with explanations
- Component-by-component breakdown (compilers, workspaces, IDE features)
- Feature location guide (IntelliSense, refactorings, analyzers, etc.)
- Architecture and design patterns (red-green trees, immutability, MEF)
- Developer workflows (adding language features, analyzers, refactorings)
- Testing strategies and debugging tips

Designed for engineers who need to quickly locate code, understand the
architecture, and make changes effectively over a 2-year period.
Created surgical guide for modifying the C# language (06-compiler-internals.md):

PARSER (60+ files mapped):
- LanguageParser.cs (652KB) - Main parser with all key methods
- Lexer.cs (186KB) - Tokenization engine
- Specialized parsers for patterns, interpolated strings, etc.
- Exact methods to modify for new syntax

BINDER (30+ files mapped):
- Binder_Expressions.cs (594KB) - All expression binding
- Binder_Statements.cs (204KB) - All statement binding
- Binder_Operators.cs (317KB) - Operator resolution
- Binder_Patterns.cs (99KB) - Pattern matching
- Complete scope binder hierarchy

SYMBOLS:
- Core symbol types (TypeSymbol, MethodSymbol, etc.)
- Source symbols vs metadata symbols
- Synthesized symbols for compiler-generated code
- Symbol construction and substitution

LOWERING (60+ LocalRewriter files):
- LocalRewriter_BinaryOperator.cs (126KB)
- LocalRewriter_ForEachStatement.cs (66KB) - foreach → while
- LocalRewriter_UsingStatement.cs - using → try/finally
- Async/await state machine generation
- Iterator state machine generation
- Closure conversion and lambda capturing

FLOW ANALYSIS:
- DefiniteAssignment.cs (126KB)
- NullableWalker.cs (656KB) - Nullable analysis
- Control flow and reachability analysis

CODE GENERATION:
- EmitExpression.cs (178KB) - IL for expressions
- EmitStatement.cs (87KB) - IL for statements
- Complete IL emission pipeline

ERROR SYSTEM:
- ErrorCode.cs - All compiler errors/warnings
- Error message templates and diagnostics

MODIFICATION WORKFLOWS:
- Step-by-step: Add new operator
- Step-by-step: Add new statement type
- Step-by-step: Add pattern matching feature
- Language feature reference (where each C# feature is implemented)

This provides surgical precision for any C# language modification.

Also updated README.md to highlight compiler internals documentation.
@dotnet-policy-service dotnet-policy-service bot added the Community The pull request was submitted by a contributor who is not a Microsoft employee. label Nov 21, 2025
@Crypties Crypties closed this Nov 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Area-Compilers Community The pull request was submitted by a contributor who is not a Microsoft employee.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants