doc-comment-0.3.1/.gitignore010064400007650000024000000000221325712072500141250ustar0000000000000000Cargo.lock target doc-comment-0.3.1/.travis.yml010064400007650000024000000004221346133546700142620ustar0000000000000000language: rust rust: - nightly - beta - stable - 1.24.1 script: - rustc --version - (rustc --version | grep nightly && echo "nightly build!") || touch not_nightly - cargo build - cargo test - if [ ! -f not_nightly ]; then cargo test --features no_core; fi doc-comment-0.3.1/build.rs010064400007650000024000000013451346133544500136170ustar0000000000000000use std::process::Command; fn main() { if let Ok(v) = Command::new("rustc").arg("--version").output() { let s = match String::from_utf8(v.stdout) { Ok(s) => s, _ => return, }; if !s.starts_with("rustc ") { return; } if let Some(s) = s.split(' ').skip(1).next() { let s = s.split('.').collect::>(); if s.len() < 3 { return; } if s[0] == "1" && u32::from_str_radix(&s[1], 10) .map(|nb| nb < 30) .unwrap_or_else(|_| false) { println!("cargo:rustc-cfg=feature=\"old_macros\""); } } } }doc-comment-0.3.1/Cargo.toml.orig010064400007650000024000000007151346133553400150400ustar0000000000000000[package] name = "doc-comment" version = "0.3.1" authors = ["Guillaume Gomez "] documentation = "http://docs.rs/crate/doc-comment" repository = "https://github.com/GuillaumeGomez/doc-comment" readme = "README.md" license = "MIT" description = "Macro to generate doc comments" build = "build.rs" [lib] name = "doc_comment" [badges] travis-ci = { repository = "GuillaumeGomez/doc-comment" } [features] no_core = [] old_macros = [] doc-comment-0.3.1/Cargo.toml0000644000000017220000000000000113010ustar00# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies # # If you believe there's an error in this file please file an # issue against the rust-lang/cargo repository. If you're # editing this file be aware that the upstream Cargo.toml # will likely look very different (and much more reasonable) [package] name = "doc-comment" version = "0.3.1" authors = ["Guillaume Gomez "] build = "build.rs" description = "Macro to generate doc comments" documentation = "http://docs.rs/crate/doc-comment" readme = "README.md" license = "MIT" repository = "https://github.com/GuillaumeGomez/doc-comment" [lib] name = "doc_comment" [features] no_core = [] old_macros = [] [badges.travis-ci] repository = "GuillaumeGomez/doc-comment" doc-comment-0.3.1/LICENSE010064400007650000024000000020601325711362000131420ustar0000000000000000MIT License Copyright (c) 2018 Guillaume Gomez Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. doc-comment-0.3.1/README.md010064400007650000024000000015411346133304600134220ustar0000000000000000# doc-comment [![][img_travis-ci]][travis-ci] [![][img_crates]][crates] [![][img_doc]][doc] [img_travis-ci]: https://api.travis-ci.org/GuillaumeGomez/doc-comment.png?branch=master [travis-ci]: https://travis-ci.org/GuillaumeGomez/doc-comment [img_crates]: https://img.shields.io/crates/v/doc-comment.svg [crates]: https://crates.io/crates/doc-comment [img_doc]: https://img.shields.io/badge/rust-documentation-blue.svg Write doc comments from macros. ## Usage example ````rust // Of course, we need to import the `doc_comment` macro: #[macro_use] extern crate doc_comment; // If you want to test examples in your README file. doctest!("../README.md"); // If you want to document an item: doc_comment!(concat!("fooo", "or not foo"), pub struct Foo {}); ```` For more information, take a look at the [documentation][doc]. [doc]: https://docs.rs/doc-comment/doc-comment-0.3.1/src/lib.rs010064400007650000024000000123531346133271400140520ustar0000000000000000// // Doc comment // // Copyright (c) 2018 Guillaume Gomez // #![cfg_attr(feature = "no_core", feature(no_core))] #![cfg_attr(feature = "no_core", no_core)] #![cfg_attr(not(feature = "no_core"), no_std)] //! The point of this (small) crate is to allow you to add doc comments from macros or //! to test external markdown files' code blocks through `rustdoc`. //! //! It's especially useful when generating types with macros. For example: //! //! ``` //! // The macro which generates types //! macro_rules! gen_types { //! ($tyname:ident) => { //! /// This is a wonderful generated struct! //! /// //! /// You can use it as follow: //! /// //! /// ``` //! /// let x = FirstOne { //! /// field1: 0, //! /// field2: 0, //! /// field3: 0, //! /// field4: 0, //! /// }; //! /// //! /// println!("Created a new instance of FirstOne: {:?}", x); //! /// ``` //! #[derive(Debug)] //! pub struct $tyname { //! pub field1: u8, //! pub field2: u16, //! pub field3: u32, //! pub field4: u64, //! } //! } //! } //! //! // Now let's actually generate types: //! gen_types!(FirstOne); //! gen_types!(SecondOne); //! gen_types!(Another); //! ``` //! //! So now we have created three structs with different names, but they all have the exact same //! documentation, which is an issue for any structs not called `FirstOne`. That's where //! [`doc_comment!`] macro comes in handy! //! //! Let's rewrite the `gen_types!` macro: //! //! // Of course, we need to import the `doc_comment` macro: //! #[macro_use] //! extern crate doc_comment; //! //! macro_rules! gen_types { //! ($tyname:ident) => { //! doc_comment! { //! concat!("This is a wonderful generated struct! //! //! You can use it as follow: //! //! ``` //! let x = ", stringify!($tyname), " { //! field1: 0, //! field2: 0, //! field3: 0, //! field4: 0, //! }; //! //! println!(\"Created a new instance of ", stringify!($tyname), ": {:?}\", x); //! ```"), //! #[derive(Debug)] //! pub struct $tyname { //! pub field1: u8, //! pub field2: u16, //! pub field3: u32, //! pub field4: u64, //! } //! } //! } //! } //! //! gen_types!(FirstOne); //! gen_types!(SecondOne); //! gen_types!(Another); //! # fn main() {} //! //! Now each struct has doc which match itself! //! //! Now let's assume you want to test code examples in your `README.md` file which //! looks like this: //! //! ````text //! # A crate //! //! Here is a code example: //! //! ```rust //! let x = 2; //! assert!(x != 0); //! ``` //! ```` //! //! You can use the `doc_comment!` macro to test it like this: //! //! ``` //! #[macro_use] //! extern crate doc_comment; //! //! // When running `cargo test`, rustdoc will check this file as well. //! doc_comment!(include_str!("../README.md")); //! # fn main() {} //! ``` //! //! Please note that can also use the `doctest!` macro to have a shorter way to test an outer //! file: //! //! ``` //! #[macro_use] //! extern crate doc_comment; //! //! doctest!("../README.md"); //! # fn main() {} //! ``` /// This macro can be used to generate documentation upon a type/item (or just to test outer /// markdown file code examples). /// /// # Example /// /// ``` /// #[macro_use] /// extern crate doc_comment; /// /// // If you just want to test an outer markdown file: /// doc_comment!(include_str!("../README.md")); /// /// // If you want to document an item: /// doc_comment!("fooo", pub struct Foo {}); /// # fn main() {} /// ``` #[macro_export] macro_rules! doc_comment { ($x:expr) => { #[doc = $x] extern {} }; ($x:expr, $($tt:tt)*) => { #[doc = $x] $($tt)* }; } /// This macro provides a simpler way to test an outer markdown file. /// /// # Example /// /// ``` /// extern crate doc_comment; /// /// // The two next lines are doing exactly the same thing: /// doc_comment::doc_comment!(include_str!("../README.md")); /// doc_comment::doctest!("../README.md"); /// /// // If you want to have a name for your tests: /// doc_comment::doctest!("../README.md", another); /// # fn main() {} /// ``` #[cfg(not(feature = "old_macros"))] #[macro_export] macro_rules! doctest { ($x:expr) => { doc_comment::doc_comment!(include_str!($x)); }; ($x:expr, $y:ident) => { doc_comment::doc_comment!(include_str!($x), mod $y {}); }; } /// This macro provides a simpler way to test an outer markdown file. /// /// # Example /// /// ``` /// #[macro_use] /// extern crate doc_comment; /// /// // The two next lines are doing exactly the same thing: /// doc_comment!(include_str!("../README.md")); /// doctest!("../README.md"); /// /// // If you want to have a name for your tests: /// doctest!("../README.md", another); /// # fn main() {} /// ``` #[cfg(feature = "old_macros")] #[macro_export] macro_rules! doctest { ($x:expr) => { doc_comment!(include_str!($x)); }; ($x:expr, $y:ident) => { doc_comment!(include_str!($x), mod $y {}); }; } doc-comment-0.3.1/.cargo_vcs_info.json0000644000000001120000000000000132730ustar00{ "git": { "sha1": "9a633728a23669dcacf879d75559ea842322a31c" } }