Document the gfx_select! macro.

wgpu-core/src/lib.rs

@@ -196,6 +196,31 @@ If you are running this program on native and not in a browser and wish to work
 Adapter::downlevel_properties or Device::downlevel_properties to get a listing of the features the current \
 platform supports.";
 
+/// Call a `Global` method, dispatching dynamically to the appropriate back end.
+///
+/// Uses of this macro have the form:
+///
+///     gfx_select!(id => global.method(args...))
+///
+/// where `id` is some [`id::Id`] resource id, `global` is a [`hub::Global`],
+/// and `method` is any method on [`Global`] that takes a single `A: HalApi`
+/// generic parameter (for example, [`Global::device_create_buffer`]).
+///
+/// The `wgpu-core` crate can support multiple back ends simultaneously (Vulkan,
+/// Metal, etc.), depending on features and availability. Each [`Id`]'s value
+/// indicates which back end its resource belongs to. This macro does a switch
+/// on `id`'s back end, and calls the `Global` method specialized for that back
+/// end.
+///
+/// Internally to `wgpu-core`, most types take the back end as a generic
+/// parameter, so their methods are compiled with full knowledge of which back
+/// end they're working with. This macro serves as the boundary between dynamic
+/// `Id` values used by `wgpu-core`'s users and the crate's mostly-monomorphized
+/// implementation.
+///
+/// [`Global`]: hub::Global
+/// [`Global::device_create_buffer`]: hub::Global::device_create_buffer
+/// [`Id`]: id::Id
 #[macro_export]
 macro_rules! gfx_select {
     ($id:expr => $global:ident.$method:ident( $($param:expr),* )) => {