Skip to content

Commit

Permalink
Improve the way proc macros are documented
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@LukasKalbertodt
LukasKalbertodt committed Sep 7, 2019
1 parent 9e6ce72 commit 527a359
Show file tree
Hide file tree
Showing 4 changed files with 195 additions and 211 deletions.
25 changes: 4 additions & 21 deletions lox-macros/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand Down
162 changes: 4 additions & 158 deletions src/io/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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;
Expand Down
Loading

0 comments on commit 527a359

Please sign in to comment.