docs: document stdlib re-exports in errors package

[ankurs]

Summary

• Add new sections to the errors howto page covering Is, As, Unwrap, Join, and Cause — now that feat: re-export stdlib errors for drop-in replacement errors#30 re-exports all stdlib error functions
• Update the Packages page description to reflect the drop-in replacement capability

Test plan

• Verify CI / Playwright tests pass (no page paths or nav structure changed, content-only update)
• Visual review of rendered howto/errors page

Summary by CodeRabbit

• Documentation
  • Updated Errors package docs to describe current behavior: drop-in compatibility with Go standard errors, automatic stack-trace capture, gRPC status integration, re-exported standard helper functions, and error notification support.
  • Added user-facing error-handling guides with examples for checking errors, finding root causes, combining multiple errors, and unwrapping errors for diagnostics.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1354e657-7049-47fc-8d43-3a19acbe526e

📥 Commits

Reviewing files that changed from the base of the PR and between c7234c0 and 22ddbb6.

📒 Files selected for processing (1)

• howto/errors.md

🚧 Files skipped from review as they are similar to previous changes (1)

• howto/errors.md

---

📝 Walkthrough

Walkthrough

Documentation updated for the Errors package: Packages.md now describes it as a drop-in replacement for Go's standard errors (adds stack trace capture and gRPC status code integration); howto/errors.md adds examples for checking, finding root causes, combining, and unwrapping errors.

Changes

Cohort / File(s)	Summary
Package Description Packages.md	Replaced previous description (compatibility with golang.org/pkg/errors) with wording that the package is a drop-in replacement for Go's standard errors, noting stack trace capture, gRPC status code integration, re-exported standard helpers (Is, As, Unwrap, Join), and a Notifier sub-package for error notification.
How‑To Guide Additions howto/errors.md	Added sections and Go examples for checking errors (errors.Is, errors.As), finding root causes (errors.Cause, ErrorExt.Cause()), combining errors (errors.Join), and unwrapping errors (errors.Unwrap). Removed one blank line in an example.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through docs with glee,
Traced each error back to the tree,
I joined the bits and found the cause,
Unwrapped the layers, checked the laws,
Now stack traces sparkle — hip hooray! 🥕✨

🚥 Pre-merge checks | ✅ 3

✅ 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 summarizes the main change: documenting stdlib re-exports in the errors package, which aligns with adding new sections covering stdlib helper functions (Is, As, Unwrap, Join) to the errors documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/errors-stdlib-drop-in

---

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: 1

🧹 Nitpick comments (2)

howto/errors.md (1)

80-80: Consider softening “All standard library error functions” phrasing.

This can become stale if Go adds new helpers; “including …” is safer long-term wording.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@howto/errors.md` at line 80, The sentence "All standard library error
functions are re-exported" is too absolute; change the wording to a safer
phrasing such as "Common standard library error functions are re-exported" or
"Standard library error helpers (including errors.Is and errors.As) are
re-exported" so it doesn't claim completeness; update the line that mentions
import "errors" and the examples referencing errors.Is and errors.As to use the
new phrasing.

Packages.md (1)

38-38: Tighten wording to avoid “all vs listed subset” ambiguity.

“All standard library functions” plus a short list can be read as contradictory. Prefer “including” (or “such as”) for precision.

Suggested wording

-A drop-in replacement for the standard `errors` package that adds stack trace capture, gRPC status codes, and error notification support. All standard library functions (`Is`, `As`, `Unwrap`, `Join`) are re-exported.
+A drop-in replacement for the standard `errors` package that adds stack trace capture, gRPC status codes, and error notification support. Standard library helpers, including `Is`, `As`, `Unwrap`, and `Join`, are re-exported.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Packages.md` at line 38, Update the sentence to avoid implying completeness:
replace "All standard library functions (`Is`, `As`, `Unwrap`, `Join`) are
re-exported." with wording that uses "including" or "such as" so it reads e.g.
"Standard library functions including `Is`, `As`, `Unwrap`, and `Join` are
re-exported." This keeps the reference to the `errors` package and the listed
symbols (`Is`, `As`, `Unwrap`, `Join`) but removes the ambiguous "All" claim.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@howto/errors.md`:
- Around line 82-106: The example snippets reference sql.ErrNoRows and
fmt.Println but only import github.com/go-coldbrew/errors; update the import
list to include "database/sql" and "fmt" (or remove those usages) so the
examples are copy-paste runnable—specifically adjust the import block used by
the examples and ensure the functions/values (sql.ErrNoRows, fmt.Println) used
in the errors.Is/errors.As/errors.Cause examples are declared via those imports.

---

Nitpick comments:
In `@howto/errors.md`:
- Line 80: The sentence "All standard library error functions are re-exported"
is too absolute; change the wording to a safer phrasing such as "Common standard
library error functions are re-exported" or "Standard library error helpers
(including errors.Is and errors.As) are re-exported" so it doesn't claim
completeness; update the line that mentions import "errors" and the examples
referencing errors.Is and errors.As to use the new phrasing.

In `@Packages.md`:
- Line 38: Update the sentence to avoid implying completeness: replace "All
standard library functions (`Is`, `As`, `Unwrap`, `Join`) are re-exported." with
wording that uses "including" or "such as" so it reads e.g. "Standard library
functions including `Is`, `As`, `Unwrap`, and `Join` are re-exported." This
keeps the reference to the `errors` package and the listed symbols (`Is`, `As`,
`Unwrap`, `Join`) but removes the ambiguous "All" claim.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d2c7928e-fe70-42a2-94a7-2921752e9969

📥 Commits

Reviewing files that changed from the base of the PR and between 3012603 and ff7c2e4.

📒 Files selected for processing (2)

• Packages.md
• howto/errors.md

[Copilot]

Pull request overview

Updates ColdBrew docs to reflect that github.com/go-coldbrew/errors now re-exports the Go standard library errors helpers, positioning it more explicitly as a drop-in replacement.

Changes:

• Expanded howto/errors.md with new sections covering Is, As, Unwrap, Join, and Cause.
• Updated Packages.md to describe errors as a drop-in replacement that re-exports stdlib error helpers.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
Packages.md	Refreshes the high-level package description to emphasize drop-in replacement + stdlib re-exports.
howto/errors.md	Adds usage guidance/examples for stdlib-style error inspection and composition via the ColdBrew errors package.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.