dirmod_docsrs_test/lib.rs
1//! # dirmod
2//! [](https://travis-ci.om/SOF3/dirmod)
3//! [](https://crates.io/crates/dirmod)
4//! [](https://crates.io/crates/dirmod)
5//! [](https://sof3.github.io/dirmod/)
6//! [](https://github.com/SOF3/dirmod)
7//!
8//! Tired of writing and updating all the `mod` statements in mod.rs?
9//! Generate them with `dirmod` instead.
10//!
11//! `dirmod` scans your directory and generates the corresponding `mod` statements automatically
12//! with a simple macro call:
13//!
14//! ```ignore
15//! dirmod::all!();
16//! ```
17//!
18//! And that's all!
19//!
20//! > *(Note: `dirmod` is designed for [Rust 2018 Edition](https://doc.rust-lang.org/edition-guide/rust-2018/index.html),
21//! so macros take simple and ambiguous names like `all`, `os`, etc.
22//! It is recommended to call the macros in fully-qualified fashion
23//! like `dirmod::all!`, `dirmod::os!()`, etc. for clarity.
24//! The old `#[macro_use] extern crate dirmod;` style is not recommended.)*
25//!
26//! ## Visibility
27//! Modules can be set to a common visibility,
28//! so all modules can be `pub mod` or `pub(self) mod`, etc. by default at your favour:
29//!
30//! ```ignore
31//! dirmod::all!(default pub);
32//! ```
33//!
34//! You can also make all modules private, and set the visibility for the *re-exported* items instead.
35//!
36//! If there are individual modules among dozens that need special visibility configuration,
37//! it is also possible to write
38//!
39//! ```ignore
40//! dirmod::all!(default pub; priv foo, bar);
41//! ```
42//!
43//! Then all modules have `pub` visibility,
44//! except `foo` and `bar` which are private.
45//!
46//! ## Conditional compilation
47//! > But I use `mod` to implement conditional compilation!
48//!
49//! No problem, `dirmod` generates `cfg` attributes for some idiomatic styles:
50//! - A directory where each module name is the feature name (e.g. `#[cfg(feature = "foo")] mod foo;`)
51//! - A directory where each module name is the OS/OS family name (e.g. `#[cfg(target_family = "unix")] mod unix;`)
52//!
53//! This can be achieved by calling `dirmod::os!()`, `dirmod::family!()` or `dirmod::feature!()`.
54//!
55//! It is likely that different OS variants of the same module expose the same API,
56//! so it might be practical to write:
57//!
58//! ```ignore
59//! dirmod::os!(pub use);
60//! ```
61//!
62//! If none of the modules support the current OS, you could trigger a compile error:
63//!
64//! ```ignore
65//! dirmod::os!(pub use ||);
66//! ```
67//!
68//! Or with a custom error message:
69//!
70//! ```ignore
71//! dirmod::os!(pub use || "custom error message");
72//! ```
73//!
74//! Note that it does not make sense to use the `||` on `dirmod::feature!`,
75//! because Cargo features are incremental and should not be restricted in amount.
76//!
77//! [File an issue](https://github.com/SOF3/dirmod) if I missed any common styles!
78//!
79//! ## But I am still unhappy about xxxx corner case!
80//! No problem, you don't have to use `dirmod` for every module.
81//! `dirmod::all!()` has an `except` argument that excludes certain modules.
82//! Since the macro simply generates `mod` statements,
83//! it is perfectly fine to add more items before/after the macro call.
84//!
85//! ```ignore
86//! dirmod::all!(except corge, grault);
87//! ```
88//!
89//! ## Documentation
90//! Instead of writing docs in mod.rs, write them in the module directly.
91//! In addition to `dirmod` constraints, there are a few advantages:
92//!
93//! - Avoid lots of docs mixed together in a single mod.rs. Easier to navigate!
94//! - Writing docs inside the module itself is much more relevant than references to the parent module.
95//!
96//! To write docs for the module, use this syntax at the top of the module (before any other items):
97//!
98//! ```ignore
99//! //! Yay, I'm now describing myself!
100//! //! I finally have my own place!
101//! ```
102//!
103//! ## Supported Rust versions
104//! Since detecting the source file requires the [`proc_macro_span`](https://github.com/rust-lang/rust/issues/54725) feature,
105//! Rust Nightly is required to compile this crate.
106//!
107//! ## Examples
108//! See the [`testcrate`](https://github.com/SOF3/dirmod/tree/master/testcrate) directory, which demonstrates the use of `dirmod::all!` and `dirmod::family!`.
109
110pub use dirmod::*;