Skip to content

Include documentation of explicit shim trait impls in rustdoc of ExternType #742

Open
@dtolnay

Description

@dtolnay

The content in https://cxx.rs/extern-c++.html#explicit-shim-trait-impls would be good to copy or at least link from https://docs.rs/cxx/1.0.32/cxx/trait.ExternType.html. The whole point of ExternType is to enable using Rust types defined outside of the current bridge, and requiring some CXX shim trait impl on those types is absolutely the kind of thing that comes up, which makes ExternType documentation a natural place people would think to look for documentation of how to make it work.

Privately shared anecdote:

As a quick suggestion: it might be worth referencing this from the ExternType page that mentions how you can share types across crates (https://docs.rs/cxx/1.0.32/cxx/trait.ExternType.html). I spent a little while trying to figure this out and looking into cxx's code before I eventually found the "declare a useless struct" workaround

The user had discovered that the following results in the right impls they need being generated:

#[cxx::bridge]
mod ffi {
    /* ... */

    struct _ForceCxxImpl {
        f1: UniquePtr<ProcessorEventHandler>,
        f2: SharedPtr<ProcessorEventHandler>,
    }
}

without finding out about the recommended approach of doing:

    impl UniquePtr<ProcessorEventHandler> {}
    impl SharedPtr<ProcessorEventHandler> {}

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsNeeds better documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions