GitHub PullRequestReviewCommentEvent at 2014-04-30 16:05:33
Repository: rust
Actor: alexcrichton
Payload: {"comment":{"url":"https://api.github.com/repos/mozilla/rust/pulls/comments/12151079","id":12151079,"diff_hunk":"@@ -0,0 +1,263 @@\n+// Copyright 2014 The Rust Project Developers. See the COPYRIGHT\n+// file at the top-level directory of this distribution and at\n+// http://rust-lang.org/COPYRIGHT.\n+//\n+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or\n+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license\n+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your\n+// option. This file may not be copied, modified, or distributed\n+// except according to those terms.\n+\n+//! The `bitflags!` macro generates a `struct` that holds a set of C-style\n+//! bitmask flags. It is useful for creating typesafe wrappers for C APIs.\n+//!\n+//! The flags should only be defined for integer types, otherwise unexpected\n+//! type errors may occur at compile time.\n+//!\n+//! # Example\n+//!\n+//! ~~~rust\n+//! #![feature(phase)]\n+//! #[phase(syntax)] extern crate collections;\n+//!\n+//! bitflags!(Flags: u32 {\n+//!     FlagA       = 0x00000001,\n+//!     FlagB       = 0x00000010,\n+//!     FlagC       = 0x00000100,\n+//!     FlagABC     = FlagA.bits\n+//!                 | FlagB.bits\n+//!                 | FlagC.bits\n+//! })\n+//!\n+//! fn main() {\n+//!     let e1 = FlagA | FlagC;\n+//!     let e2 = FlagB | FlagC;\n+//!     assert!((e1 | e2) == FlagABC);   // union\n+//!     assert!((e1 & e2) == FlagC);     // intersection\n+//!     assert!((e1 - e2) == FlagA);     // set difference\n+//! }\n+//! ~~~\n+//!\n+//! The generated `struct`s can also be extended with type and trait implementations:\n+//!\n+//! ~~~rust\n+//! #![feature(phase)]\n+//! #[phase(syntax)] extern crate collections;\n+//!\n+//! use std::fmt;\n+//!\n+//! bitflags!(Flags: u32 {\n+//!     FlagA   = 0x00000001,\n+//!     FlagB   = 0x00000010\n+//! })\n+//!\n+//! impl Flags {\n+//!     pub fn clear(&mut self) {\n+//!         self.bits = 0;  // The `bits` field can be accessed from within the\n+//!                         // same module where the `bitflags!` macro was invoked.\n+//!     }\n+//! }\n+//!\n+//! impl fmt::Show for Flags {\n+//!     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {\n+//!         write!(f.buf, \"hi!\")\n+//!     }\n+//! }\n+//!\n+//! fn main() {\n+//!     let mut flags = FlagA | FlagB;\n+//!     flags.clear();\n+//!     assert!(flags.is_empty());\n+//!     assert_eq!(format!(\"{}\", flags), ~\"hi!\");\n+//! }\n+//! ~~~\n+//!\n+//! # Derived traits\n+//!\n+//! The `Eq`, `TotalEq`, and `Clone` traits are automatically derived for the\n+//! `struct` using the `deriving` attribute.\n+//!\n+//! # Operators\n+//!\n+//! The following operator traits are implemented for the generated `struct`:\n+//!\n+//! - `BitOr`: union\n+//! - `BitAnd`: intersection\n+//! - `Sub`: set difference\n+//!\n+//! # Methods\n+//!\n+//! The following methods are defined for the generated `struct`:\n+//!\n+//! - `empty`: an empty set of flags\n+//! - `bits`: the raw value of the flags currently stored\n+//! - `is_empty`: `true` if no flags are currently stored\n+//! - `intersects`: `true` if there are flags common to both `self` and `other`\n+//! - `contains`: `true` all of the flags in `other` are contained within `self`\n+//! - `insert`: inserts the specified flags in-place\n+//! - `remove`: removes the specified flags in-place","path":"src/libstd/bitflags.rs","position":98,"original_position":98,"commit_id":"0c58e86ee9970edaea935a245ce04916730d1176","original_commit_id":"0c58e86ee9970edaea935a245ce04916730d1176","user":{"login":"alexcrichton","id":64996,"avatar_url":"https://avatars.githubusercontent.com/u/64996?","gravatar_id":"477e2098d9864b482d28e5ef8e657f43","url":"https://api.github.com/users/alexcrichton","html_url":"https://github.com/alexcrichton","followers_url":"https://api.github.com/users/alexcrichton/followers","following_url":"https://api.github.com/users/alexcrichton/following{/other_user}","gists_url":"https://api.github.com/users/alexcrichton/gists{/gist_id}","starred_url":"https://api.github.com/users/alexcrichton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alexcrichton/subscriptions","organizations_url":"https://api.github.com/users/alexcrichton/orgs","repos_url":"https://api.github.com/users/alexcrichton/repos","events_url":"https://api.github.com/users/alexcrichton/events{/privacy}","received_events_url":"https://api.github.com/users/alexcrichton/received_events","type":"User","site_admin":false},"body":"Now that we can put documentation on macros themselves, I wonder if this would be best suited on the macro itself.\r\n\r\nI suppose if you search for `bitflags` you'll probably hit the module before the macro, though.","created_at":"2014-04-30T16:05:33Z","updated_at":"2014-04-30T16:05:33Z","html_url":"https://github.com/mozilla/rust/pull/13072#discussion_r12151079","pull_request_url":"https://api.github.com/repos/mozilla/rust/pulls/13072","_links":{"self":{"href":"https://api.github.com/repos/mozilla/rust/pulls/comments/12151079"},"html":{"href":"https://github.com/mozilla/rust/pull/13072#discussion_r12151079"},"pull_request":{"href":"https://api.github.com/repos/mozilla/rust/pulls/13072"}}}}