Improve the way proc macros are documented

This moves documentation of derive macros from the trait to the
reexport. And it removes the dirty hack for `mesh!`. This was possible
because this issue was closed:
   rust-lang/rust#58700

Author: LukasKalbertodt

lox-macros/src/lib.rs

@@ -16,9 +16,7 @@ mod derives;
 mod mesh;
 
 
-/// See [`lox::mesh_macro`][dummy] for documentation.
-///
-/// [dummy]: ../lox/macro.mesh_macro.html
+// See [`lox::mesh`][../lox/macro.mesh.html] for documentation.
 #[proc_macro]
 pub fn mesh(input: TokenStream) -> TokenStream {
     use crate::mesh::MeshInput;
@@ -30,12 +28,7 @@ pub fn mesh(input: TokenStream) -> TokenStream {
 }
 
 
-/// Custom derive for the `Empty` trait.
-///
-/// See [the documentation of the `Empty` trait in `lox`][trait] for more information
-/// about this derive.
-///
-/// [trait]: ../lox/traits/trait.Empty.html
+// See main crate (`lox`) for documentation.
 #[proc_macro_derive(Empty)]
 pub fn derive_empty(input: TokenStream) -> TokenStream {
     let input = syn::parse_macro_input!(input as DeriveInput);
@@ -45,12 +38,7 @@ pub fn derive_empty(input: TokenStream) -> TokenStream {
 }
 
 
-/// Custom derive for the `MemSink` trait.
-///
-/// See [the documentation of the `MemSink` trait in `lox`][trait] for more
-/// information about this derive.
-///
-/// [trait]: ../lox/io/trait.MemSink.html
+// See main crate (`lox`) for documentation.
 #[proc_macro_derive(MemSink, attributes(lox))]
 pub fn derive_mem_sink(input: TokenStream) -> TokenStream {
     let input = syn::parse_macro_input!(input as DeriveInput);
@@ -60,12 +48,7 @@ pub fn derive_mem_sink(input: TokenStream) -> TokenStream {
         .into()
 }
 
-/// Custom derive for the `MemSource` trait.
-///
-/// See [the documentation of the `MemSource` trait in `lox`][trait] for more
-/// information about this derive.
-///
-/// [trait]: ../lox/io/trait.MemSource.html
+// See main crate (`lox`) for documentation.
 #[proc_macro_derive(MemSource, attributes(lox))]
 pub fn derive_mem_source(input: TokenStream) -> TokenStream {
     let input = syn::parse_macro_input!(input as DeriveInput);

src/io/mod.rs

@@ -1245,118 +1245,8 @@ where
 ///
 /// # Deriving
 ///
-/// You can easily derive this trait for your own types. To derive this trait,
-/// you have to attach `#[derive(MemSink)]` to your struct definition (note:
-/// currently, the trait can only be derived for structs with named fields).
-/// You also have to annotate your fields with `#[lox(...)]` attributes to tell
-/// the derive macro what a field should be used for. Example:
-///
-/// ```
-/// use lox::{
-///     MemSink, VertexHandle,
-///     cgmath::Point3,
-///     ds::HalfEdgeMesh,
-///     map::DenseMap,
-/// };
-///
-///
-/// #[derive(MemSink)]
-/// struct MyMesh {
-///     #[lox(core_mesh)]
-///     mesh: HalfEdgeMesh,
-///
-///     #[lox(vertex_position)]
-///     positions: DenseMap<VertexHandle, Point3<f32>>,
-/// }
-/// ```
-///
-/// There is one required field: the core mesh field. That field's type has to
-/// implement several mesh traits, in particular `MeshMut` and `TriMeshMut`.
-/// You have to annotate that mesh with `#[lox(core_mesh)]`.
-///
-/// Additionally, you can have fields for each mesh property, like vertex
-/// position or face colors. The type of those fields has to implement
-/// `PropStoreMut` with a compatible element type. You have to annotate these
-/// property fields with the corresponding attribute. The available properties
-/// are:
-///
-/// - `vertex_position`
-/// - `vertex_normal`
-/// - `vertex_color`
-/// - `face_normal`
-/// - `face_color`
-///
-/// Furthermore, there are some configurations (like the cast mode) that can be
-/// configured via `lox(...)` attributes as well. See below for more
-/// information.
-///
-///
-/// ### Cast modes
-///
-/// You can set a *cast mode* for each field. A `MemSink` has to be able to
-/// "handle" any primitive type as the source is allowed to call the property
-/// methods with any type. The sink can handle types either by casting or by
-/// returning an error. The field's cast mode determines which casts are
-/// allowed and which are not. Possible cast modes:
-///
-/// - `cast = "none"`
-/// - `cast = "lossless"`
-/// - `cast = "rounding"`
-/// - `cast = "clamping"`
-/// - `cast = "lossy"` (*default*)
-///
-/// The `none` mode does not allow casting at all. If the type provided by the
-/// source does not match the type in your struct, an error is returned. All
-/// other modes correspond to the cast modes in the [`cast`
-/// module][crate::cast].
-///
-/// Note that the cast modes are used by `derive(MemSource)` as well.
-///
-/// You can specify the cast mode either per field or globally on the whole
-/// struct. The mode of the struct applies to all fields that don't have a
-/// field-specific mode.
-///
-/// ```
-/// # use lox::{
-/// #     MemSink, VertexHandle,
-/// #     cgmath::{Point3, Vector3},
-/// #     ds::HalfEdgeMesh,
-/// #     map::DenseMap,
-/// # };
-/// #
-/// #[derive(MemSink)]
-/// #[lox(cast = "none")]
-/// struct MyMesh {
-///     #[lox(core_mesh)]
-///     mesh: HalfEdgeMesh,
-///
-///     #[lox(vertex_position)]
-///     positions: DenseMap<VertexHandle, Point3<f32>>,
-///
-///     #[lox(vertex_normal, cast = "lossy")]
-///     normals: DenseMap<VertexHandle, Vector3<f32>>,
-/// }
-/// ```
-///
-/// In this example, the vertex positions inherit the "struct global" cast mode
-/// (`none`), while the vertex normals override that mode to `lossy`.
-///
-///
-/// ### Exact traits required for each field
-///
-/// Traits required for the `core_mesh` field:
-/// - TODO
-///
-/// Traits required for property fields. For type `T` of the field:
-/// - `T` must implement [`PropStoreMut`][crate::map::PropStoreMut] (with
-///   fitting handle type). Additionally:
-///     - For `vertex_position`: `T::Target` must implement
-///       [`Pos3Like`][crate::prop::Pos3Like].
-///     - For `*_normal`: `T::Target` must implement
-///       [`Vec3Like`][crate::prop::Vec3Like].
-///     - For `*_color`: `T::Target` must implement
-///       [`ColorLike`][crate::prop::ColorLike] and `T::Target::Channel` must
-///       implement [`Primitive`].
+/// You can easily derive this trait for your own types. See [the derive
+/// macro's documentation](../derive.MemSink.html) for more information.
 pub trait MemSink {
     // =======================================================================
     // ===== Mesh connectivity
@@ -1606,52 +1496,8 @@ where
 ///
 /// # Deriving
 ///
-/// You can easily derive this trait for your own types. To derive this trait,
-/// you have to attach `#[derive(MemSource)]` to your struct definition (note:
-/// currently, the trait can only be derived for structs with named fields).
-/// You also have to annotate your fields with `#[lox(...)]` attributes to tell
-/// the derive macro what a field should be used for. Example:
-///
-/// ```
-/// use lox::{
-///     MemSource, VertexHandle,
-///     cgmath::Point3,
-///     ds::SharedVertexMesh,
-///     map::DenseMap,
-/// };
-///
-///
-/// #[derive(MemSource)]
-/// struct MyMesh {
-///     #[lox(core_mesh)]
-///     mesh: SharedVertexMesh,
-///
-///     #[lox(vertex_position)]
-///     positions: DenseMap<VertexHandle, Point3<f32>>,
-/// }
-/// ```
-///
-/// Deriving this trait works very similar to deriving [`MemSink`]. See its
-/// documentation for more information on the custom derive.
-///
-///
-/// ### Exact traits required for each field
-///
-/// Traits required for the `core_mesh` field:
-/// - TODO
-///
-/// Traits required for property fields. For type `T` of the field:
-/// - `T` must implement [`PropStore`][crate::map::PropStore] (with fitting
-///   handle type). Additionally:
-///     - For `vertex_position`: `T::Target` must implement
-///       [`Pos3Like`][crate::prop::Pos3Like] and `T::Target::Scalar` must
-///       implement [`Primitive`].
-///     - For `*_normal`: `T::Target` must implement
-///       [`Vec3Like`][crate::prop::Vec3Like] and `T::Target::Scalar` must
-///       implement [`Primitive`].
-///     - For `*_color`: `T::Target` must implement
-///       [`ColorLike`][crate::prop::ColorLike] and `T::Target::Channel` must
-///       implement [`Primitive`].
+/// You can easily derive this trait for your own types. See [the derive
+/// macro's documentation](../derive.MemSource.html) for more information.
 pub trait MemSource {
     /// The type of the core mesh.
     type CoreMesh: TriMesh + BasicAdj;