docs: separate README contents to other files

[arika0093]

Summary by CodeRabbit

• Documentation
  • Restructured README into a streamlined Quick Start, installation-focused flow, and consolidated usage guidance
  • Added a comprehensive docs suite: Installation, Usage Patterns, FAQ, Performance, Library Comparison, and feature guides (array nullability, auto-generated comments, local-variable capture, nested DTO naming, partial classes, global properties)
  • Improved navigation, shorter targeted examples, and links to detailed guides for deeper customization and examples

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@arika0093 has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 20 minutes and 35 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between df3213a and 5ed3f7f.

📒 Files selected for processing (1)

• README.md (4 hunks)

Walkthrough

The repository's documentation was reorganized: README.md was streamlined into a Quick Start and installation-focused layout, and a new docs/library collection (installation, usage patterns, feature guides, comparisons, performance, FAQ, and global properties) was added. No code or public API changes.

Changes

Cohort / File(s)	Change Summary
README restructuring README.md	Rewrote README to a concise Quick Start and installation-oriented narrative, removed long inline setup and examples, and added navigation links to the new documentation pages.
Installation & setup docs/library/installation.md	New installation and prerequisites guide (C#/.NET requirements, NuGet install commands, csproj snippets, PolySharp notes, next steps).
Usage patterns docs/library/usage-patterns.md	New guide describing Anonymous, Explicit DTO, and Pre-existing DTO patterns with examples, generated snippets, IEnumerable usage, and extension via partial classes.
Feature guides docs/library/array-nullability.md, docs/library/auto-generated-comments.md, docs/library/local-variable-capture.md, docs/library/nested-dto-naming.md, docs/library/partial-classes.md	Five new feature docs covering array nullability removal rules and config, auto-generated XML comments and config, local variable capture pattern and analyzer support, nested DTO naming strategies and options, and extending generated partial DTOs.
Configuration & global properties docs/library/global-properties.md	New reference documenting MSBuild/global properties (LinqraftGlobalNamespace, LinqraftRecordGenerate, LinqraftPropertyAccessor, LinqraftHasRequired, LinqraftCommentOutput, LinqraftArrayNullabilityRemoval, LinqraftNestedDtoUseHashNamespace) with examples and inspection tips.
Reference & comparison docs/library/library-comparison.md, docs/library/performance.md, docs/library/faq.md	Three new reference docs: library comparison (AutoMapper, Mapster, Mapperly, Facet, Linqraft), performance/benchmark results and methodology, and an FAQ covering common usage and generated code access.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Focus review on cross-reference accuracy between README and docs and quick syntax checks of embedded code examples.

Poem

🐰 Hop along through docs so neat,
Features gathered, all complete!
From quick-starts bright to patterns wise,
Knowledge blooms before our eyes!
Installation guides now show the way—
Welcome, travelers, to learn today! 🌟

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main objective: separating README contents into individual documentation files across docs/library/.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2a039c0 and c994e89.

📒 Files selected for processing (12)

• README.md (4 hunks)
• docs/library/array-nullability.md (1 hunks)
• docs/library/auto-generated-comments.md (1 hunks)
• docs/library/faq.md (1 hunks)
• docs/library/global-properties.md (1 hunks)
• docs/library/installation.md (1 hunks)
• docs/library/library-comparison.md (1 hunks)
• docs/library/local-variable-capture.md (1 hunks)
• docs/library/nested-dto-naming.md (1 hunks)
• docs/library/partial-classes.md (1 hunks)
• docs/library/performance.md (1 hunks)
• docs/library/usage-patterns.md (1 hunks)

🧰 Additional context used

🧠 Learnings (11)

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/**/*Helper.cs : Document complex helper methods with XML comments

Applied to files:

• docs/library/partial-classes.md
• docs/library/faq.md
• docs/library/usage-patterns.md
• README.md
• docs/library/auto-generated-comments.md
• docs/library/library-comparison.md
• docs/library/installation.md
• docs/library/global-properties.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Add test cases for source generators to `tests/Linqraft.Tests/`

Applied to files:

• docs/library/performance.md
• docs/library/faq.md
• docs/library/usage-patterns.md
• README.md
• docs/library/global-properties.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Add test cases for analyzers to `tests/Linqraft.Analyzer.Tests/`

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/**/*.cs : Keep helper methods lightweight and focused; helper methods are called frequently during analysis

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft/DummyExpression.cs : Do not edit `DummyExpression.cs`; it serves only as a marker for the Source Generator

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.{Analyzer,Core}/**/*.cs : Always prefer semantic analysis over string matching; use `RoslynTypeHelper` instead of string-based type checking

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.{Analyzer,Core}/**/*.cs : Use `ISymbolEqualityComparer` for symbol comparisons in analyzer code

Applied to files:

• README.md
• docs/library/library-comparison.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/**/*.cs : Cache expensive operations in helper methods when possible

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Analyzer/**/*Analyzer.cs : All new analyzers should inherit from `BaseLinqraftAnalyzer`

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/SyntaxHelpers/*.cs : Syntax helpers should be placed in `Linqraft.Core/SyntaxHelpers/` and named `*Helper.cs`

Applied to files:

• README.md

📚 Learning: 2025-12-05T13:51:44.986Z

Learnt from: arika0093
Repo: arika0093/Linqraft PR: 210
File: .github/workflows/test-strict.yaml:17-17
Timestamp: 2025-12-05T13:51:44.986Z
Learning: In the Linqraft repository, the library projects (src/) target netstandard2.0, which maintains compatibility with .NET 6.0 and older versions. The test matrix in .github/workflows/test-strict.yaml specifies which .NET versions are used to run tests, not the library's compatibility. Changes to the test matrix (TFMS variable) do not affect library compatibility and should not be treated as breaking changes.

Applied to files:

• docs/library/library-comparison.md
• docs/library/installation.md

🪛 markdownlint-cli2 (0.18.1)

docs/library/faq.md

129-129: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

145-145: Bare URL used

(MD034, no-bare-urls)

🔇 Additional comments (10)

README.md (3)

161-178: Approve README reorganization as navigation hub.

The restructuring successfully transforms the README from an extensive inline reference into a focused quick-start guide that directs users to detailed documentation. The layout is clean, the features are prominent, and navigation is clear. Cross-references to new docs are appropriately organized by category (Getting Started, Customization, Performance & Comparison, Help).

---

234-258: All documentation links in the README are correctly referenced and exist in the repository.

All 12 documentation files referenced in the Documentation section (lines 234–258) have been verified as present and properly formatted: installation.md, usage-patterns.md, local-variable-capture.md, array-nullability.md, partial-classes.md, nested-dto-naming.md, auto-generated-comments.md, global-properties.md, performance.md, library-comparison.md, faq.md, and docs/analyzers/README.md. No action required.

Likely an incorrect or invalid review comment.

---

232-232: Verify existence of referenced usage-patterns.md file.

Lines 232 and 239 reference ./docs/library/usage-patterns.md, but this file's existence cannot be confirmed without direct repository access. Ensure this file exists in the repository, along with other documentation files mentioned in the Documentation section (docs/library/faq.md, docs/library/performance.md, docs/library/partial-classes.md).

docs/library/installation.md (1)

59-60: Cross-reference to usage-patterns.md (pending verification).

The "Next Steps" section links to ./usage-patterns.md. Ensure this file exists, as it's also referenced in README.md. (This is the same file referenced elsewhere that needs verification.)

docs/library/local-variable-capture.md (1)

64-64: Verify image asset exists.

The documentation references an image at ../../assets/local-variable-capture-err.png (line 64). Ensure this asset file exists at the expected path relative to the docs folder structure.

docs/library/usage-patterns.md (1)

1-197: Comprehensive and well-structured usage patterns guide. The three patterns (Anonymous, Explicit DTO, Pre-existing DTO) are clearly differentiated with practical examples, generated code samples, and balanced pros/cons. The structure makes it easy for users to understand when to use each approach.

docs/library/performance.md (1)

1-44: Clear performance documentation with comprehensive benchmarks. The three key performance characteristics (compile-time code generation, native expression trees, zero dependencies) are well-explained. The benchmark table effectively compares Linqraft against popular mapping libraries, with clear methodology and environment details.

docs/library/partial-classes.md (1)

1-97: Practical guide to extending generated DTOs. The documentation clearly demonstrates how to use partial classes to add custom methods, implement interfaces, apply attributes, and control property accessibility. The generated code examples help readers understand what is auto-generated versus user-defined.

docs/library/faq.md (2)

160-165: Verify all referenced documentation files exist.

The FAQ references several documentation files for next steps. Ensure the following files exist in docs/library/:

• installation.md
• usage-patterns.md
• customization.md
• performance.md

Line 164 references customization.md—verify this file exists and is included in this PR.

---

38-89: Content quality is strong. The FAQ comprehensively covers general usage across LINQ providers, DTO usage in various contexts (API responses, services, tests), and provides two practical methods for accessing generated code. Examples are clear and well-contextualized.

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

docs/library/faq.md (1)

129-138: Add language identifier to code block for proper markdown rendering.

The folder tree code block is missing a language identifier. This violates MD040 (fenced-code-language) and impacts rendering/accessibility.

-```
+```text
 YourProject/
 ├── Generated/
 │   ├── Linqraft.SourceGenerator/
 │   │   ├── SelectExpr_HASH1.g.cs
 │   │   ├── SelectExpr_HASH2.g.cs
 │   │   └── ...
 ├── Program.cs
 └── YourProject.csproj
-```
+```

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c994e89 and df3213a.

📒 Files selected for processing (2)

• README.md (4 hunks)
• docs/library/faq.md (1 hunks)

🧰 Additional context used

🧠 Learnings (11)

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Analyzer/**/*.cs : Use `TriviaHelper` for formatting to preserve whitespace, comments, and detect line endings for cross-platform compatibility

Applied to files:

• docs/library/faq.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Add test cases for source generators to `tests/Linqraft.Tests/`

Applied to files:

• docs/library/faq.md
• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Add test cases for analyzers to `tests/Linqraft.Analyzer.Tests/`

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/**/*.cs : Keep helper methods lightweight and focused; helper methods are called frequently during analysis

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/**/*Helper.cs : Document complex helper methods with XML comments

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft/DummyExpression.cs : Do not edit `DummyExpression.cs`; it serves only as a marker for the Source Generator

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.{Analyzer,Core}/**/*.cs : Always prefer semantic analysis over string matching; use `RoslynTypeHelper` instead of string-based type checking

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.{Analyzer,Core}/**/*.cs : Use `ISymbolEqualityComparer` for symbol comparisons in analyzer code

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/**/*.cs : Cache expensive operations in helper methods when possible

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Core/SyntaxHelpers/*.cs : Syntax helpers should be placed in `Linqraft.Core/SyntaxHelpers/` and named `*Helper.cs`

Applied to files:

• README.md

📚 Learning: 2025-11-25T12:08:35.849Z

Learnt from: CR
Repo: arika0093/Linqraft PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T12:08:35.849Z
Learning: Applies to src/Linqraft.Analyzer/**/*Analyzer.cs : All new analyzers should inherit from `BaseLinqraftAnalyzer`

Applied to files:

• README.md

🪛 markdownlint-cli2 (0.18.1)

docs/library/faq.md

129-129: Fenced code blocks should have a language specified

(MD040, fenced-code-language)