Skip to content

GitLab

Commit ac831a19 authored by Federico Mena Quintero's avatar Federico Mena Quintero
Browse files
Options

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

parent 5efedece
Hide whitespace changes
Inline Side-by-side
Showing with 108 additions and 100 deletions
src/lib.rs
View file @ ac831a19
......@@ -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