Add overview of generated macro code to vulkano-shader-derive (#958)

examples/src/bin/triangle.rs

@@ -205,6 +205,10 @@ fn main() {
     //
     // The raw shader creation API provided by the vulkano library is unsafe, for various reasons.
     //
+    // An overview of what the `VulkanoShader` derive macro generates can be found in the
+    // `vulkano-shader-derive` crate docs. You can view them at
+    // https://docs.rs/vulkano-shader-derive/*/vulkano_shader_derive/
+    //
     // TODO: explain this in details
     mod vs {
         #[derive(VulkanoShader)]

vulkano-shader-derive/src/lib.rs

@@ -34,7 +34,90 @@
 //! a lot of what is generated will never be used, it's a good idea to put
 //! `#[allow(unused)]` on the module itself if you don't want to see irrelevant
 //! errors.
-//!
+//! 
+//! If you want to take a look at what the macro generates, your best options
+//! are to either read through the code that handles the generation (the
+//! [`reflect`][reflect] function in the `vulkano-shaders` crate) or use a tool
+//! such as [cargo-expand][cargo-expand] to view the expansion of the macro in your
+//! own code. It is unfortunately not possible to provide a `generated_example`
+//! module like some normal macro crates do since derive macros cannot be used from
+//! the crate they are declared in. On the other hand, if you are looking for a
+//! high-level overview, you can see the below section.
+//! 
+//! # Generated code overview
+//! 
+//! The macro generates the following items of interest:
+//! * The `Shader` struct. This contains a single field, `shader`, which is an
+//! `Arc<ShaderModule>`.
+//! * The `Shader::load` constructor. This method takes an `Arc<Device>`, calls
+//! [`ShaderModule::new`][ShaderModule::new] with the passed-in device and the
+//! shader data provided via the macro, and returns `Result<Shader, OomError>`.
+//! Before doing so, it loops through every capability instruction in the shader
+//! data, verifying that the passed-in `Device` has the appropriate features
+//! enabled. **This function currently panics if a feature required by the shader
+//! is not enabled on the device.** At some point in the future it will return
+//! an error instead.
+//! * The `Shader::module` method. This method simply returns a reference to the
+//! `Arc<ShaderModule>` contained within the `shader` field of the `Shader`
+//! struct.
+//! * Methods for each entry point of the shader module. These construct and
+//! return the various entry point structs that can be found in the
+//! [vulkano::pipeline::shader][pipeline::shader] module.
+//! * A Rust struct translated from each struct contained in the shader data.
+//! * The `Layout` newtype. This contains a [`ShaderStages`][ShaderStages] struct.
+//! An implementation of [`PipelineLayoutDesc`][PipelineLayoutDesc] is also
+//! generated for the newtype.
+//! * The `SpecializationConstants` struct. This contains a field for every
+//! specialization constant found in the shader data. Implementations of
+//! `Default` and [`SpecializationConstants`][SpecializationConstants] are also
+//! generated for the struct.
+//! 
+//! All of these generated items will be accessed through the module that you
+//! wrote to use the derive macro in. If you wanted to store the `Shader` in
+//! a struct of your own, you could do something like this:
+//! 
+//! ```
+//! # #[macro_use]
+//! # extern crate vulkano_shader_derive;
+//! # extern crate vulkano;
+//! # fn main() {}
+//! # use std::sync::Arc;
+//! # use vulkano::OomError;
+//! # use vulkano::device::Device;
+//! #
+//! # #[allow(unused)]
+//! # mod vertex_shader {
+//! #     #[derive(VulkanoShader)]
+//! #     #[ty = "vertex"]
+//! #     #[src = "
+//! # #version 450
+//! #
+//! # layout(location = 0) in vec3 position;
+//! #
+//! # void main() {
+//! #     gl_Position = vec4(position, 1.0);
+//! # }
+//! # "]
+//! #     struct Dummy;
+//! # }
+//! // various use statements
+//! // `vertex_shader` module with shader derive
+//! 
+//! pub struct Shaders {
+//!     pub vertex_shader: vertex_shader::Shader
+//! }
+//! 
+//! impl Shaders {
+//!     pub fn load(device: Arc<Device>) -> Result<Self, OomError> {
+//!         Ok(Self {
+//!             vertex_shader: vertex_shader::Shader::load(device)?,
+//!         })
+//!     }
+//! }
+//! ```
+//! 
+//! # Options
+//! 
 //! The options available are in the form of the following attributes:
 //!
 //! ## `#[ty = "..."]`
@@ -49,8 +132,7 @@
 //! * `tess_eval`
 //! * `compute`
 //!
-//! For details on what these shader types mean, [see Vulkano's documentation]
+//! For details on what these shader types mean, [see Vulkano's documentation][pipeline].
-//! (https://docs.rs/vulkano/0.7.2/vulkano/pipeline/index.html).
 //!
 //! ## `#[src = "..."]`
 //!
@@ -61,6 +143,17 @@
 //!
 //! Provides the path to the GLSL source to be compiled, relative to `Cargo.toml`.
 //! Cannot be used in conjunction with the `#[src]` attribute.
+//! 
+//! [reflect]: https://github.com/vulkano-rs/vulkano/blob/master/vulkano-shaders/src/lib.rs#L67
+//! [cargo-expand]: https://github.com/dtolnay/cargo-expand
+//! [ShaderModule::new]: https://docs.rs/vulkano/*/vulkano/pipeline/shader/struct.ShaderModule.html#method.new
+//! [OomError]: https://docs.rs/vulkano/*/vulkano/enum.OomError.html
+//! [pipeline::shader]: https://docs.rs/vulkano/*/vulkano/pipeline/shader/index.html
+//! [descriptor]: https://docs.rs/vulkano/*/vulkano/descriptor/index.html
+//! [ShaderStages]: https://docs.rs/vulkano/*/vulkano/descriptor/descriptor/struct.ShaderStages.html
+//! [PipelineLayoutDesc]: https://docs.rs/vulkano/*/vulkano/descriptor/pipeline_layout/trait.PipelineLayoutDesc.html
+//! [SpecializationConstants]: https://docs.rs/vulkano/*/vulkano/pipeline/shader/trait.SpecializationConstants.html
+//! [pipeline]: https://docs.rs/vulkano/*/vulkano/pipeline/index.html
 
 extern crate glsl_to_spirv;
 extern crate proc_macro;