doc-comment-0.3.4/.cargo_vcs_info.json0000644000000001360000000000100132450ustar { "git": { "sha1": "2cf5d3c8595374191ed587e9476e99b410f377d3" }, "path_in_vcs": "" }doc-comment-0.3.4/.github/FUNDING.yml000064400000000000000000000001401046102023000152050ustar 00000000000000# These are supported funding model platforms github: [GuillaumeGomez] patreon: GuillaumeGomez doc-comment-0.3.4/.gitignore000064400000000000000000000000221046102023000140170ustar 00000000000000Cargo.lock target doc-comment-0.3.4/.travis.yml000064400000000000000000000004221046102023000141440ustar 00000000000000language: 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.4/Cargo.lock0000644000000002330000000000100112160ustar # This file is automatically @generated by Cargo. # It is not intended for manual editing. version = 4 [[package]] name = "doc-comment" version = "0.3.4" doc-comment-0.3.4/Cargo.toml0000644000000020110000000000100112350ustar # 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 are reading this file be aware that the original Cargo.toml # will likely look very different (and much more reasonable). # See Cargo.toml.orig for the original contents. [package] name = "doc-comment" version = "0.3.4" authors = ["Guillaume Gomez "] build = "build.rs" autolib = false autobins = false autoexamples = false autotests = false autobenches = false 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" [badges.travis-ci] repository = "GuillaumeGomez/doc-comment" [features] no_core = [] old_macros = [] [lib] name = "doc_comment" path = "src/lib.rs" doc-comment-0.3.4/Cargo.toml.orig000064400000000000000000000007151046102023000147270ustar 00000000000000[package] name = "doc-comment" version = "0.3.4" 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.4/LICENSE000064400000000000000000000020601046102023000130400ustar 00000000000000MIT 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.4/README.md000064400000000000000000000023231046102023000133140ustar 00000000000000# 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. Please note that calling macros in `doc` attribute was added in Rust 1.54 so unless you need to support older Rust versions, you don't need this crate and you can do the same thing with: ```rust,no_run #[cfg_attr(doctest, doc = include_str!("../README.md"))] ``` ## 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.4/build.rs000064400000000000000000000013451046102023000135050ustar 00000000000000use 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.4/src/lib.rs000064400000000000000000000140331046102023000137410ustar 00000000000000// // 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`. //! //! Starting in Rust 1.54, this crate becomes useless as you can do the same thing //! with the `doc` attribute: //! //! ```ignore //! #[cfg_attr(doctest, doc = include_str!("../README.md"))] //! ``` //! //! ## 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 {}); }; }