cargo_e/
a_funny_docs.rs

1// // // src/a_funny_docs.rs
2
3// // // =============================
4// // // Humorous Macro Definition
5// // // =============================
6
7// // /// **HA! DIDN'T GET IT THE FIRST TIME?**
8// // ///
9// // /// This macro is your second chance to be enlightened by the absurdity of our code base.
10// // ///
11// // /// Imagine a world where every line of code bursts with humor and genius—that's what you're about to experience.
12// // /// If you're still scratching your head, don't worry; confusion is merely the first step toward brilliant epiphanies.
13// // ///
14// // /// **READ THIS, YOU ABSOLUTE GENIUS!**
15// // /// For a comprehensive, mind-blowing guide that will forever change your perspective on code and life, please check out the
16// // /// **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**.
17// // ///
18// // /// *Remember: If you missed it the first time, you'll never miss it again!*
19// // ///
20// // /// # Example
21// // ///
22// // /// ```rust
23// // /// funny_macro!();
24// // /// ```
25// // #[macro_export]
26// // #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
27// // macro_rules! funny_macro {
28// //     () => {{
29// //         println!("Your funny macro is in full swing! Have you checked out the ultimate guide yet?");
30// //     }};
31// // }
32
33// // // =============================
34// // // Humorous Module with Various Items
35// // // =============================
36
37// // /// A collection of humorous documentation items that serve no functional purpose
38// // /// except to remind you that coding can be as funny as it is brilliant.
39// // ///
40// // /// This module is packed with a constant, function, struct, enum, trait, and type alias,
41// // /// each with its own extended, side-splitting commentary. And yes, every item includes
42// // /// an undeniably large and obvious link to the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**.
43// // ///
44// // /// If the feature flag `funny-docs` is disabled, these items will be hidden from your generated documentation.
45// // #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
46// // pub mod a_funny_docs {
47// //     // A constant with a humorous twist.
48// //     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
49// //     #[doc = "**CONSTANT COMEDY ALERT:**\nIf numbers could laugh, this constant would be chuckling at the absurdity of fixed values.\n\nFor the ultimate comedy in coding, visit the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
50// //     pub const a_const: () = ();
51
52// //     // A function that tells a joke.
53// //     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
54// //     #[doc = "**FUNCTION FUNNY BUSINESS:**\nThis function doesn't do much—it's here for the giggles. Every time it's called, the universe aligns with a pun.\n\nFor more hilarity, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
55// //     pub fn a_function() {
56// //         println!("Function humor: a_function executed!");
57// //     }
58
59// //     // A struct that stands as a monument to mirth.
60// //     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
61// //     #[doc = "**STRUCTURE OF LAUGHTER:**\nThis struct is built on a foundation of humor. Its very existence is a testament to the power of a well-timed joke.\n\nFor the blueprint of comedy, see the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
62// //     pub struct AStruct;
63
64// //     // An enum whose variants are pure punchlines.
65// //     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
66// //     #[doc = "**ENUMERATE THE LAUGHTER:**\nThis enum's variants are as surprising as a punchline in the middle of a monologue. Discover the unexpected twist in every variant.\n\nFor more, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
67// //     pub enum AEnum {
68// //         #[doc = "**AVARIANT, THE PUNCHLINE:**\nThis variant is the climax of our enum saga—laugh, cry, and then laugh again."]
69// //         AVariant,
70// //     }
71
72// //     // A trait that defines a contract for comedic behavior.
73// //     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
74// //     #[doc = "**TRAIT OF TONGUE-IN-CHEEK:**\nThis trait defines behaviors with a side-splitting twist. Implement it if you want your types to perform like a stand-up comedian.\n\nFor in-depth trait-based hilarity, see the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
75// //     pub trait ATrait {
76// //         // You could define a dummy method here if desired.
77// //     }
78
79// //     // A type alias that proves brevity can be uproariously funny.
80// //     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
81// //     #[doc = "**ALIAS OF ABSURDITY:**\nThis type alias is like the punchline of a great joke: short, memorable, and guaranteed to leave an impression.\n\nWhen in doubt, refer to the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)** for a dose of coding comedy."]
82// //     pub type AType = ();
83// // }
84
85// // // =============================
86// // // Re-Exports for Public Visibility
87// // // =============================
88
89// // /// If you still haven't grasped the joke, take another look!
90// // ///
91// // /// Check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**,
92// // /// where the ultimate comedic wisdom is laid out for your enlightenment.
93// // #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
94// // pub use a_funny_docs as guide;
95
96// // /// Behold the macro that brings the laughter!
97// // /// If you didn't get it the first time, this macro is here to ensure you have a second shot at the comedy gold.
98// // /// For the full comedic effect, please see the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**.
99// // #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
100// // pub use funny_macro;
101
102// // src/a_funny_docs.rs
103
104// #![allow(dead_code)]
105
106// // For dynamic type names.
107// use paste::paste;
108
109// //
110// // Dynamic naming macro example using the paste crate.
111// //
112// // To use this, add `paste = "1.0"` to your Cargo.toml dependencies.
113// //
114
115// /// Defines a new funny struct whose name always starts with an "A" followed by the provided identifier.
116// ///
117// /// # Example
118// ///
119// /// ```rust
120// /// define_funny_struct!(CrazyDuck);
121// /// // This creates a struct named `ACrazyDuck`
122// /// ```
123// #[macro_export]
124// macro_rules! define_funny_struct {
125//     ($name:ident) => {
126//         paste::paste! {
127//             #[doc = concat!("A hilariously named struct: `A", stringify!($name), "`! It's guaranteed to make your codebase smile. For more, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**.")]
128//             pub struct [<A $name>];
129//         }
130//     };
131// }
132
133// // =============================
134// // Humorous Macro Definition
135// // =============================
136
137// /// **HA! DIDN'T GET IT THE FIRST TIME?**
138// ///
139// /// This macro is your second chance to be enlightened by the absurdity of our code base.
140// ///
141// /// Imagine a world where every line of code bursts with humor and genius—that's what you're about to experience.
142// /// If you're still scratching your head, don't worry; confusion is merely the first step toward brilliant epiphanies.
143// ///
144// /// **READ THIS, YOU ABSOLUTE GENIUS!**
145// /// For a comprehensive, mind-blowing guide that will forever change your perspective on code and life, please check out the
146// /// **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**.
147// ///
148// /// *Remember: If you missed it the first time, you'll never miss it again!*
149// ///
150// /// # Example
151// ///
152// /// ```rust
153// /// funny_macro!();
154// /// ```
155// #[macro_export]
156// #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
157// macro_rules! funny_macro {
158//     () => {{
159//         println!("Your funny macro is in full swing! Have you checked out the ultimate guide yet?");
160//     }};
161// }
162
163// // =============================
164// // Humorous Module with Various Items
165// // =============================
166
167// /// A collection of humorous documentation items that serve no functional purpose
168// /// except to remind you that coding can be as funny as it is brilliant.
169// ///
170// /// This module is packed with a constant, function, struct, enum, trait, type alias, and even a dynamically named struct,
171// /// each with its own extended, side-splitting commentary. Every item includes the unmistakable link to the
172// /// **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**.
173// ///
174// /// If the `funny-docs` feature is disabled, these items are hidden from your final generated documentation.
175// #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
176// pub mod a_funny_docs {
177//     // A constant with a humorous twist.
178//     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
179//     #[doc = "**CONSTANT COMEDY ALERT:**\nIf numbers could laugh, this constant would be chuckling at the absurdity of fixed values.\n\nFor the ultimate comedy in coding, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
180//     pub const a_const: () = ();
181
182//     // A function that tells a joke.
183//     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
184//     #[doc = "**FUNCTION FUNNY BUSINESS:**\nThis function doesn't do much—it's here for the giggles. Every time it's called, the universe aligns with a pun.\n\nFor more hilarity, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
185//     pub fn a_function() {
186//         println!("Function humor: a_function executed!");
187//     }
188
189//     // A struct that stands as a monument to mirth.
190//     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
191//     #[doc = "**STRUCTURE OF LAUGHTER:**\nThis struct is built on a foundation of humor. Its very existence is a testament to the power of a well-timed joke.\n\nFor the blueprint of comedy, see the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
192//     pub struct AStruct;
193
194//     // An enum whose variants are pure punchlines.
195//     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
196//     #[doc = "**ENUMERATE THE LAUGHTER:**\nThis enum's variants are as surprising as a punchline in the middle of a monologue. Discover the unexpected twist in every variant.\n\nFor more, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
197//     pub enum AEnum {
198//         #[doc = "**AVARIANT, THE PUNCHLINE:**\nThis variant is the climax of our enum saga—laugh, cry, and then laugh again."]
199//         AVariant,
200//     }
201
202//     // A trait that defines a contract for comedic behavior.
203//     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
204//     #[doc = "**TRAIT OF TONGUE-IN-CHEEK:**\nThis trait defines behaviors with a side-splitting twist. Implement it if you want your types to perform like a stand-up comedian.\n\nFor in-depth trait-based hilarity, see the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
205//     pub trait ATrait {
206//         // A dummy method to exemplify behavior.
207//         fn do_joke(&self) -> String;
208//     }
209
210//     // A type alias that proves brevity can be uproariously funny.
211//     #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
212//     #[doc = "**ALIAS OF ABSURDITY:**\nThis type alias is like the punchline of a great joke: short, memorable, and guaranteed to leave an impression.\n\nWhen in doubt, refer to the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)** for a dose of coding comedy."]
213//     pub type AType = ();
214
215//     // Use the dynamic naming macro to create a funny struct.
216//     define_funny_struct!(CrazyDuck);
217// }
218
219// // =============================
220// // Re-Exports for Public Visibility
221// // =============================
222
223// /// If you still haven't grasped the joke, take another look!
224// ///
225// /// Check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**,
226// /// where the ultimate comedic wisdom is laid out for your enlightenment.
227// #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
228// pub use a_funny_docs as guide;
229
230// /// Behold the macro that brings the laughter!
231// /// If you didn't get it the first time, this macro is here to ensure you have a second shot at the comedy gold.
232// /// For the full comedic effect, please see the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**.
233// #[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
234// pub use funny_macro;
235
236// // =============================
237// // Inline Tests to Exercise Everything
238// // =============================
239// #[cfg(test)]
240// mod tests {
241//     use super::a_funny_docs::*;
242//     use super::*;
243
244//     #[test]
245//     fn test_constant() {
246//         // Exercise the constant.
247//         let _ = a_const;
248//     }
249
250//     #[test]
251//     fn test_function() {
252//         // Exercise the function.
253//         a_function();
254//     }
255
256//     #[test]
257//     fn test_struct() {
258//         // Instantiate the struct.
259//         let _instance = AStruct;
260//     }
261
262//     #[test]
263//     fn test_enum() {
264//         // Match on the enum.
265//         match AEnum::AVariant {
266//             AEnum::AVariant => (),
267//         }
268//     }
269
270//     struct Dummy;
271
272//     impl a_funny_docs::ATrait for Dummy {
273//         fn do_joke(&self) -> String {
274//             "I'm a dummy telling a dummy joke!".to_string()
275//         }
276//     }
277
278//     #[test]
279//     fn test_trait() {
280//         let dummy = Dummy;
281//         assert_eq!(dummy.do_joke(), "I'm a dummy telling a dummy joke!");
282//     }
283
284//     #[test]
285//     fn test_type_alias() {
286//         // Use the type alias.
287//         let _x: AType = ();
288//     }
289
290//     #[test]
291//     fn test_dynamic_struct() {
292//         // Using the dynamically named struct from the macro.
293//         // This type was generated by `define_funny_struct!(CrazyDuck)` and is named `ACrazyDuck`.
294//         let _instance: crate::a_funny_docs::ACrazyDuck = crate::a_funny_docs::ACrazyDuck;
295//     }
296
297//     #[test]
298//     fn test_funny_macro() {
299//         // Capture the output of the funny macro.
300//         funny_macro!();
301//     }
302// }
303
304#![allow(dead_code)]
305#![allow(non_upper_case_globals)]
306
307// Bring in the paste crate for dynamic naming.
308#[cfg(feature = "uses_paste")]
309use paste::paste;
310
311// ----------------------------------------------------------------
312// Dynamic Naming Macro (Local Version)
313// ----------------------------------------------------------------
314
315/// Defines a new funny struct whose name always starts with an "A" followed by the provided identifier.
316///
317/// # Example
318///
319/// ```rust
320/// #[cfg(feature = "uses_paste")]
321/// use paste::paste;
322/// cargo_e::define_funny_struct!(CrazyDuck);
323/// // This creates a struct named `ACrazyDuck`
324/// ```
325#[cfg(feature = "uses_paste")]
326#[macro_export]
327macro_rules! define_funny_struct {
328    ($name:ident) => {
329        paste! {
330            #[doc = concat!(
331                "A hilariously named struct: `A",
332                stringify!($name),
333                "`! It's guaranteed to make your codebase smile. For more, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."
334            )]
335            pub struct [<A $name>];
336        }
337    };
338}
339
340// ----------------------------------------------------------------
341// Humorous Macro Definition (Exported)
342// ----------------------------------------------------------------
343
344/// **HA! DIDN'T GET IT THE FIRST TIME?**
345///
346/// This macro is your second chance to be enlightened by the absurdity of our code base.
347///
348/// Imagine a world where every line of code bursts with humor and genius—that's what you're about to experience.
349/// If you're still scratching your head, don't worry; confusion is merely the first step toward brilliant epiphanies.
350///
351/// **READ THIS, YOU ABSOLUTE GENIUS!**
352/// For a comprehensive, mind-blowing guide that will forever change your perspective on code and life, please check out the
353/// **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**.
354///
355/// *Remember: If you missed it the first time, you'll never miss it again!*
356///
357/// # Example
358///
359/// ```rust
360/// cargo_e::funny_macro!();
361/// ```
362#[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
363#[macro_export]
364macro_rules! funny_macro {
365    () => {{
366        println!("Your funny macro is in full swing! Have you checked out the ultimate guide yet?");
367    }};
368}
369
370// ----------------------------------------------------------------
371// Humorous Items Defined Directly
372// ----------------------------------------------------------------
373
374#[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
375#[doc = "**CONSTANT COMEDY ALERT:**\nIf numbers could laugh, this constant would be chuckling at the absurdity of fixed values.\n\nFor the ultimate comedy in coding, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
376pub const A_CONST: () = ();
377
378#[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
379#[doc = "**FUNCTION FUNNY BUSINESS:**\nThis function doesn't do much—it's here for the giggles. Every time it's called, the universe aligns with a pun.\n\nFor more hilarity, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
380pub fn a_function() {
381    println!("Function humor: a_function executed!");
382}
383
384#[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
385#[doc = "**STRUCTURE OF LAUGHTER:**\nThis struct is built on a foundation of humor. Its very existence is a testament to the power of a well-timed joke.\n\nFor the blueprint of comedy, see the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
386pub struct AStruct;
387
388#[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
389#[doc = "**ENUMERATE THE LAUGHTER:**\nThis enum's variants are as surprising as a punchline in the middle of a monologue. Discover the unexpected twist in every variant.\n\nFor more, check out the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
390pub enum AEnum {
391    #[doc = "**AVARIANT, THE PUNCHLINE:**\nThis variant is the climax of our enum saga—laugh, cry, and then laugh again."]
392    AVariant,
393}
394
395#[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
396#[doc = "**TRAIT OF TONGUE-IN-CHEEK:**\nThis trait defines behaviors with a side-splitting twist. Implement it if you want your types to perform like a stand-up comedian.\n\nFor in-depth trait-based hilarity, see the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)**."]
397pub trait ATrait {
398    fn do_joke(&self) -> String;
399}
400
401#[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
402#[doc = "**ALIAS OF ABSURDITY:**\nThis type alias is like the punchline of a great joke: short, memorable, and guaranteed to leave an impression.\n\nWhen in doubt, refer to the **[ULTIMATE GUIDE FOR YOU TO READ](./index.html)** for a dose of coding comedy."]
403pub type AType = ();
404
405// ----------------------------------------------------------------
406// Use the Dynamic Naming Macro to Create a Funny Struct
407// ----------------------------------------------------------------
408#[cfg(feature = "uses_paste")]
409define_funny_struct!(CrazyDuck);
410// This creates a struct named `ACrazyDuck` in this module.
411
412// ----------------------------------------------------------------
413// Re-Exports for Public Visibility
414// ----------------------------------------------------------------
415
416#[cfg_attr(not(feature = "funny-docs"), doc(hidden))]
417#[doc = "If you still haven't grasped the joke, take another look!\n\nCheck out the **[ULTIMATE GUIDE FOR YOU TO READ](../index.html)**, where the ultimate comedic wisdom is laid out for your enlightenment."]
418pub mod guide {
419    pub use super::*;
420}
421
422// ----------------------------------------------------------------
423// Inline Tests to Exercise Everything
424// ----------------------------------------------------------------
425
426#[cfg(test)]
427mod tests {
428    use super::*;
429
430    #[test]
431    // This approach uses std::mem::drop to consume the value of A_CONST (even though it's just ())
432    // without creating a binding. It's a neat trick to silence the "no effect" warning while keeping
433    // the intent fun and explicit.
434    #[allow(dropping_copy_types)]
435    fn test_epic_void_drop() {
436        // Instead of binding A_CONST to underscore, we simply drop it.
437        // This is our unique way of showing that we care about nothing!
438        // calls to `std::mem::drop` with a value that implements `Copy` does nothing
439        // `#[warn(dropping_copy_types)]` on by default
440        std::mem::drop(A_CONST);
441        //calls to `std::mem::drop` with a value that implements `Copy` does nothing
442    }
443
444    #[test]
445    /// Tests that `a_function` does what it does—presumably, something functionally awesome.
446    fn test_function() {
447        a_function();
448    }
449
450    #[test]
451    /// Creates an instance of `AStruct` to prove that structs can be instantiated
452    /// even if they don't have a personality (or much else) to show.
453    fn test_struct() {
454        let _instance = AStruct;
455    }
456
457    #[test]
458    /// Matches against `AEnum::AVariant`—because even enums like to have their moment in the spotlight.
459    fn test_enum() {
460        match AEnum::AVariant {
461            AEnum::AVariant => (),
462        }
463    }
464
465    /// Implements `ATrait` for a dummy type just to confirm that even dummy jokes are valid,
466    /// and that our trait really does have a punchline.
467    struct Dummy;
468
469    impl ATrait for Dummy {
470        fn do_joke(&self) -> String {
471            "I'm a dummy telling a dummy joke!".to_string()
472        }
473    }
474
475    #[test]
476    /// Creates a dummy and verifies that the joke is as laughable as expected.
477    fn test_trait() {
478        let dummy = Dummy;
479        assert_eq!(dummy.do_joke(), "I'm a dummy telling a dummy joke!");
480    }
481
482    #[test]
483    /// Tests that the type alias `AType` works as intended,
484    /// because even type aliases deserve a little bit of the limelight.
485    fn test_type_alias() {
486        let _x: AType = ();
487    }
488
489    #[test]
490    /// Tests the dynamic struct `ACrazyDuck`—a wild duck that defies both logic and gravity.
491    fn test_dynamic_struct() {
492        // ACrazyDuck is defined directly in this module.
493        let _instance: ACrazyDuck = ACrazyDuck;
494    }
495
496    #[test]
497    /// Executes the `funny_macro!` macro, proving that even macros can bring a little humor to your code.
498    fn test_funny_macro() {
499        funny_macro!();
500    }
501}
cargo_e/a_funny_docs.rs

cargo_e/
a_funny_docs.rs
