Skip to content

docs: surface MessageField/EnumValue From conveniences; add "where's #[derive]?" pointer #249

Description

@iainmcgin

Two small doc gaps surfaced by the rust_serialization_benchmark integration, where a third-party contributor and the suite maintainer both wrote the verbose form of code that buffa already had a one-call convenience for, and concluded the library was awkward rather than that they'd missed the convenience.

1. Surface the From conveniences on MessageField / EnumValue

These have existed since 0.1.0 but aren't in the type-level rustdoc examples, so users reach for the explicit constructors:

Written in the wild Available since 0.1.0
buffa::MessageField::some(x) x.into()
field.into_option().unwrap() field.unwrap() (0.8.0)
buffa::EnumValue::from(E::from(x)) E::from(x).into()
opt.map(|v| ...).into() for Option<T> → MessageField<T> opt.map(|v| ...).into() ✓ works, but undocumented

Fix: add a "Construction" / "Conversion" example block to the MessageField and EnumValue type docs showing .into() as the idiomatic form, and link it from the guide's "populating messages" section.

2. "Where's #[derive(Message)]?" pointer

Per the rationale in #226: add a short section to the crate-level docs and docs/migration-from-prost.md that pre-empts the question — "for tests/examples use buffa-test-fixtures (#226); for application code generate from .proto; here's why there's no production derive." Users coming from prost look for the derive first and currently find nothing.

Both are docs-only; no API change.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions