Added documentation to vulkano_shader_derive (#909)

This isn't full documentation of everything that the crate generates,
but it at least covers how to use it. I'm only working off my reading
of the source code, so it's entirely possible I got things wrong, but
crappy documentation is better than no documentation. I think.

Note that this has to add vulkano itself as a dev-dependency in order
for the doctest to compile, but that's also going to help with writing
tests if that ever happens.

An improvement over this would be to detail what the proc macro itself
generates and the functions, structs, etc you get from it. The details
on that are in vulkan-shaders, and are a bit harder to decipher.

vulkano-shader-derive/Cargo.toml

@@ -16,3 +16,6 @@ proc-macro = true
 glsl-to-spirv = { version = "0.1.2", path = "../glsl-to-spirv" }
 syn = { version = "0.11.11", features = ["aster", "visit"] }
 vulkano-shaders = { version = "0.7", path = "../vulkano-shaders" }
+
+[dev-dependencies]
+vulkano = "0.7.2"

vulkano-shader-derive/src/lib.rs

@@ -1,3 +1,67 @@
+//! Procedural Macro glue for compile-time compilation of GLSL into SPIR-V
+//!
+//! # Basic usage
+//!
+//! ```
+//! #[macro_use]
+//! extern crate vulkano_shader_derive;
+//! extern crate vulkano;
+//! # fn main() {}
+//! #[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;
+//! }
+//! ```
+//!
+//! # Details
+//!
+//! Due to the current limitations of procedural shaders in Rust, the current
+//! functionality of this crate is to base everything off of deriving
+//! `VulkanoShader` for a dummy struct that never actually gets used. When
+//! derived, the unused struct itself will be replaced by the functionality
+//! needed to use the shader in a Vulkano application. Due to the fact that
+//! 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.
+//!
+//! The options available are in the form of the following attributes:
+//!
+//! ## `#[ty = "..."]`
+//!
+//! This defines what shader type the given GLSL source will be compiled into.
+//! The type can be any of the following:
+//!
+//! * `vertex`
+//! * `fragment`
+//! * `geometry`
+//! * `tess_ctrl`
+//! * `tess_eval`
+//! * `compute`
+//!
+//! For details on what these shader types mean, [see Vulkano's documentation]
+//! (https://docs.rs/vulkano/0.7.2/vulkano/pipeline/index.html).
+//!
+//! ## `#[src = "..."]`
+//!
+//! Provides the raw GLSL source to be compiled in the form of a string. Cannot
+//! be used in conjunction with the `#[path]` attribute.
+//!
+//! ## `#[path = "..."]`
+//!
+//! Provides the path to the GLSL source to be compiled, relative to `Cargo.toml`.
+//! Cannot be used in conjunction with the `#[src]` attribute.
+
 extern crate glsl_to_spirv;
 extern crate proc_macro;
 extern crate syn;