Move the macro's docs to the toplevel of the crate

parent 5efedece
......@@ -2,6 +2,110 @@
// While under active devel, these warnings are kind of annoying.
#![allow(dead_code)]
//! Generates code to create a derived `glib::Object`
//!
//! This procedural macro defines an extension to the Rust language so
//! that one can create GObject implementations using only safe code.
//! All the boilerplate needed to register the GObject type, its
//! signals and properties, etc., is automatically generated.
//!
//! # Syntax overview {#syntax-overview}
//!
//! The macro is invoked as follows:
//!
//! ```norun
//! #[macro_use]
//! extern crate glib; // see "Necessary imports" below on why this is needed
//! use gobject_gen::gobject_gen;
//!
//! gobject_gen! {
//! class Foo {
//! private_field: Cell<u32>,
//! }
//!
//! // 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());
//! }
//!
//! virtual fn a_virtual_method(&self) {
//! // default handler implementation goes here
//! }
//!
//! signal fn clicked(&self);
//! }
//! }
//! ```
//!
//! Read on for the details on how to use GObject features.
//!
//! # Instance-private data
//!
//! GObject classes defined through this macro can have instance-private data
//! declared as struct fields inside the class.
//!
//! * **Declaration:** Declare struct fields inside `class Foo { ... }`
//!
//! * **Initialization:** Implement the `Default` trait for your
//! struct members, either with `#[derive(Default)]` or with an `impl Default`
//! if its missing. Note that you have to do this for each type used across
//! fields. When the generated code needs to initialize the instance-private
//! data, it will do so by calling the `Default::default()` method and assign it
//! to the internally private structure generated by the macro.
//!
//! * **Drop:** When the GObject instance gets finalized, your private
//! data will be `drop()`ed. You can provide `impl Drop` for any fields
//! that need explicit resource management.
//!
//! ## Example: instance-private data with default values
//!
//! ```norun
//! #[derive(Default)]
//! gobject_gen! {
//! class Foo {
//! field_one: Cell<u32>,
//! field_two: Cell<u16>,
//! ...
//! last_field: Cell<u8>
//! }
//! }
//! ```
//!
//! # Declaring methods
//!
//! FIXME
//!
//! # Declaring signals
//!
//! FIXME
//!
//! # ABI considerations
//!
//! FIXME
//!
//! # Necessary imports
//!
//! The generated code depends on external crates which you must put in your `Cargo.toml`:
//!
//! * The `glib` crate and its macros.
//! * The `gobject_gen` crate, declaring `proc_macro` use.
//!
//! You can put this at the top of your crate's main file:
//!
//! ```norun
//! #![feature(proc_macro)]
//! extern crate gobject_gen;
//!
//! #[macro_use]
//! extern crate glib;
//!
//! use gobject_gen::gobject_gen;
//! ```
//!
#[macro_use]
extern crate quote;
extern crate difference;
......@@ -29,109 +133,13 @@ mod hir;
mod ident_ext;
mod param;
use quote::ToTokens;
/// Generates the code to create a derived glib::Object
///
/// This procedural macro defines an extension to the Rust language so
/// that one can create GObjects using only safe code. All the
/// boilerplate needed to register the GObject type, its signals and
/// properties, etc., is automatically generated.
///
/// # Syntax overview {#syntax-overview}
///
/// The macro is invoked as follows:
///
/// ```norun
/// #[macro_use]
/// extern crate glib; // see "Necessary imports" below on why this is needed
/// use gobject_gen::gobject_gen;
///
/// gobject_gen! {
/// class Foo {
/// private_field: Cell<u32>,
/// }
///
/// // 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());
/// }
///
/// virtual fn a_virtual_method(&self) {
/// // default handler implementation goes here
/// }
///
/// signal fn clicked(&self);
/// }
/// }
/// ```
///
/// Read on for the details on how to use GObject features.
///
/// # Instance-private data
///
/// GObject classes defined through this macro can have instance-private data
/// declared as struct fields inside the class.
///
/// * **Declaration:** Declare struct fields inside `class Foo { ... }`
///
/// * **Initialization:** Implement the `Default` trait for your
/// struct members, either with `#[derive(Default)]` or with an `impl Default`
/// if its missing. Note that you have to do this for each type used across
/// fields. When the generated code needs to initialize the instance-private
/// data, it will do so by calling the `Default::default()` method and assign it
/// to the internally private structure generated by the macro.
///
/// * **Drop:** When the GObject instance gets finalized, your private
/// data will be `drop()`ed. You can provide `impl Drop` for any fields
/// that need explicit resource management.
///
/// ## Example: instance-private data with default values
///
/// ```norun
/// #[derive(Default)]
/// gobject_gen! {
/// class Foo {
/// field_one: Cell<u32>,
/// field_two: Cell<u16>,
/// ...
/// last_field: Cell<u8>
/// }
/// }
/// ```
///
/// # Declaring methods
///
/// FIXME
///
/// # Declaring signals
///
/// FIXME
///
/// # ABI considerations
///
/// FIXME
///
/// # Necessary imports
///
/// The generated code depends on external crates which you must put in your `Cargo.toml`:
///
/// * The `glib` crate and its macros.
/// * The `gobject_gen` crate, declaring `proc_macro` use.
///
/// You can put this at the top of your crate's main file:
///
/// ```norun
/// #![feature(proc_macro)]
/// extern crate gobject_gen;
///
/// #[macro_use]
/// extern crate glib;
///
/// use gobject_gen::gobject_gen;
/// ```
/// See the [crate's toplevel documentation][crate] for usage instructions.
///
/// [crate]: index.html
#[proc_macro]
#[cfg_attr(rustfmt, rustfmt_skip)]
pub fn gobject_gen(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment