doc-comment-0.3.3/.github/FUNDING.yml010064400017500001750000000001401363100152400153060ustar0000000000000000# These are supported funding model platforms github: [GuillaumeGomez] patreon: GuillaumeGomez doc-comment-0.3.3/.gitignore010064400017500001750000000000221357652242600141410ustar0000000000000000Cargo.lock target doc-comment-0.3.3/.travis.yml010064400017500001750000000004221357652242600142660ustar0000000000000000language: 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.3/Cargo.toml.orig010064400017500001750000000007151363416171100150400ustar0000000000000000[package] name = "doc-comment" version = "0.3.3" 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.3/Cargo.toml0000644000000017221363416225200113460ustar00# 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.3" 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.3/LICENSE010064400017500001750000000020601357652242600131620ustar0000000000000000MIT 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.3/README.md010064400017500001750000000017121363100152400134160ustar0000000000000000# 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 test your README file ONLY on "cargo test": #[cfg(doctest)] 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.3/build.rs010064400017500001750000000013451357652242600136270ustar0000000000000000use 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.3/src/lib.rs010064400017500001750000000135171363416166100140640ustar0000000000000000// // 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`. //! //! ## Including file(s) for testing //! //! 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: //! //! ```no_run //! #[macro_use] //! extern crate doc_comment; //! //! doctest!("../README.md"); //! # fn main() {} //! ``` //! //! Please also note that you can use `#[cfg(doctest)]`: //! //! ```no_run //! # #[macro_use] //! # extern crate doc_comment; //! #[cfg(doctest)] //! doctest!("../README.md"); //! # fn main() {} //! ``` //! //! In this case, the examples in the `README.md` file will only be run on `cargo test`. You //! can find more information about `#[cfg(doctest)]` in [this blogpost](https://blog.guillaume-gomez.fr/articles/2020-03-07+cfg%28doctest%29+is+stable+and+you+should+use+it). //! //! ## Generic documentation //! //! Now let's imagine you want to write documentation once for multiple types but //! still having examples specific to each type: //! //! ``` //! // 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! /// 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.3/.cargo_vcs_info.json0000644000000001121363416225200133400ustar00{ "git": { "sha1": "c978310dc3554a834bc3cdc9f555a5df036507b1" } }