Docs: examining generated code

Cargo.toml

@@ -11,8 +11,8 @@ proc-macro = true
 test = false
 
 [features]
-#If this feature is enabled, it's executes the tests with the rust-files
-#generated during an earlier run.
+# If this feature is enabled, it executes the tests with the
+# rust files generated during an earlier run.
 test-generated = []
 
 [dependencies]

src/lib.rs

@@ -4,7 +4,7 @@
 
 //! Generates code to create a derived `glib::Object`
 //!
-//! This procedural macro defines an extension to the Rust language so
+//! The `gobject_gen!` macro defines an extension to the Rust language so
 //! that one can create GObject implementations, or define
 //! GTypeInterfaces, using only safe code.  All the boilerplate needed
 //! to register the GObject type, its signals and properties, etc., is
@@ -15,8 +15,9 @@
 //! The macro is invoked as follows:
 //!
 //! ```norun
+//! // see "Necessary imports" below on why this is needed
 //! #[macro_use]
-//! extern crate glib;  // see "Necessary imports" below on why this is needed
+//! extern crate glib;
 //! use gobject_gen::gobject_gen;
 //!
 //! gobject_gen! {
@@ -25,12 +26,13 @@
 //!         another_field: RefCell<String>,
 //!     }
 //!
-//!     // Methods and signals;, their order defines the ABI of your class
+//!     // Methods and signals; their order defines
+//!     // the ABI of your class
 //!     impl Foo {
 //!         pub fn a_static_method(&self) {
 //!             // self.get_priv() gives us access to the private
-//!fields declared in class Foo
-//!             do_something_with_u32(self.get_priv().private_field.get());
+//!             // fields declared in class Foo
+//!             do_something(self.get_priv().private_field.get());
 //!         }
 //!
 //!         virtual fn a_virtual_method(&self) {
@@ -63,13 +65,15 @@
 //! use gobject_gen::gobject_gen;
 //! ```
 //!
-//! You also need the following dependencies in `Cargo.toml`:
+//! You need the following dependencies in `Cargo.toml`:
 //!
 //! ```norun
 //! [dependencies]
+//! glib = "0.5.0"
 //! glib-sys = "0.6.0"
 //! gobject-sys = "0.6.0"
 //! libc = "0.2"
+//! ```
 //!
 //! # Instance-private data
 //!
@@ -101,8 +105,45 @@
 //!
 //! FIXME
 //!
+//! # Debugging aids and examining generated code
 //!
-
+//! With gnome-class still under development, you may need to examine
+//! the code that gets generated from the procedural macro.  First,
+//! create a directory called `generated` under your crate's toplevel
+//! directory.  Then, put a `generate` attribute for your class, like
+//! this:
+//!
+//! ```norun
+//! #[cfg(feature = "test-generated")]
+//! include!("generated/foo-gen.rs");
+//! 
+//! #[cfg(not(feature = "test-generated"))]
+//! gobject_gen! {
+//!    #[generate("generated/foo-gen.rs")]
+//!     class Foo {
+//!     }
+//! }
+//! ```
+//!
+//! Correspondingly, add this to `Cargo.toml` to declare the `test-generated` feature:
+//!
+//! ```norun
+//! [features]
+//! # If this feature is enabled, it executes the tests with
+//! # the rust files generated during an earlier run.
+//! test-generated = []
+//! ```
+//!
+//! If you just `cargo build` your code, then it will output the file
+//! `generated/foo-gen.rs` which you can examine.  You can then edit
+//! that file and rebuild with `cargo build -- --features test-generated` - this will cause
+//! the `foo-gen.rs` to get included, instead of using "fresh" generated code.
+//!
+//! **Remember that changes to the generated code will be overwritten
+//! the next time the procedural macro runs!** Don't forget to [report
+//! a bug][bugs] if gnome-class is generating incorrect code for you!
+//!
+//! [bugs]: https://gitlab.gnome.org/federico/gnome-class/issues
 #[macro_use]
 extern crate quote;
 extern crate difference;