docs: surface MessageField/EnumValue From conveniences and derive guidance

[Yong-yuan-X]

Summary

• Add type-level rustdoc examples showing idiomatic .into() construction and direct unwrap() usage for MessageField.
• Add type-level rustdoc examples showing .into() conversions for known and unknown EnumValue values.
• Update the guide and prost migration examples to use the documented conversion conveniences.
• Explain why production message types are generated from .proto files and link to buffa-test-fixtures: minimal #[derive(Message)] for tests and doc examples #226 for the proposed test-fixture derive.
• Add a changelog fragment for the documentation improvements.

This is a documentation-only change with no API or codegen changes.

Testing

• cargo fmt --all --check
• cargo clippy --workspace --all-targets -- -D warnings
• cargo rustdoc -p buffa --all-features -- -D warnings
• npx.cmd --yes markdownlint-cli@0.47.0 docs/guide.md docs/migration-from-prost.md
• cargo test -p buffa --doc MessageField
• cargo test -p buffa --doc EnumValue

Closes #249

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[iainmcgin]

[claude code] Thanks for this — #249 asked for exactly these two things (surface the .into() conveniences, answer "where's the derive?"), and the conversions you documented are the right ones: I checked each From impl the examples lean on and they all exist with the shown signatures.

I pushed one commit (8db91ab) rather than sending it back to you. Four things, two of which are worth explaining:

The MessageField example was teaching a panic. The local Address type in it has no DefaultInstance impl, which means Deref — the whole reason MessageField exists, and the thing the guide sells two sections earlier as "eliminating unwrap ceremony" — isn't available on it, so the only way to read the value back was field.unwrap(). The example therefore showcased the panicking path on the type designed to avoid it, and doc examples get copied into production code. It now uses the Person doctest fixture and reads through deref (field.name), including the unset case derefing to the default instance instead of panicking.

Both examples were no_run, so every assert_eq! in them was decorative — compiled, never executed. Dropped it on both; they're self-contained and pass. They now genuinely guard the behavior they document (message_field.rs line 286 and enumeration.rs line 66 both run under cargo test --doc).

The other two: the # Where is #[derive(Message)]? heading had landed in the middle of # Quick start, so on docs.rs the DecodeOptions example and the recursion/unknown-field-limit paragraph rendered underneath a heading asking about derive macros — moved it below Quick start. And I dropped the paragraph citing #226 for buffa-test-fixtures from lib.rs: rustdoc is snapshotted per release, so "issue #226 proposes X, it is not currently available" freezes into every future version's docs the day #226 is closed or changes shape. The prost migration guide keeps a live tracking link, which is the right home for it since repo docs track main. While there I gave migration-from-protobuf.md the same derive answer as the prost guide (it still said "Implement Message by hand"), and hid the enum example's impl Enumeration scaffolding behind # lines so the four .into() lines that matter are what a reader sees.

Gates on the merged branch: cargo fmt --check, RUSTDOCFLAGS='-D warnings' cargo doc --all-features (this one caught a redundant link target in my own edit), and cargo test -p buffa --doc (15 pass) all clean.

Approving — thank you for picking this up, and for a genuinely accurate set of examples.