src/test/rustdoc-gui/src/test_docs/lib.rs

   1 //! The point of this crate is to be able to have enough different "kinds" of
   2 //! documentation generated so we can test each different features.
   3
   4 #![crate_name = "test_docs"]
   5 #![feature(rustdoc_internals)]
   6 #![feature(doc_cfg)]
   7
   8 use std::convert::AsRef;
   9 use std::fmt;
  10
  11 /// Basic function with some code examples:
  12 ///
  13 /// ```
  14 /// println!("nothing fancy");
  15 /// println!("but with two lines!");
  16 /// ```
  17 ///
  18 /// A failing to compile one:
  19 ///
  20 /// ```compile_fail
  21 /// println!("where did my argument {} go? :'(");
  22 /// ```
  23 ///
  24 /// An ignored one:
  25 ///
  26 /// ```ignore (it's a test)
  27 /// Let's say I'm just some text will ya?
  28 /// ```
  29 ///
  30 /// An inlined `code`!
  31 pub fn foo() {}
  32
  33 /// Just a normal struct.
  34 pub struct Foo;
  35
  36 impl Foo {
  37     #[must_use]
  38     pub fn must_use(&self) -> bool {
  39         true
  40     }
  41 }
  42
  43 impl AsRef<str> for Foo {
  44     fn as_ref(&self) -> &str {
  45         "hello"
  46     }
  47 }
  48
  49 /// Just a normal enum.
  50 ///
  51 /// # title!
  52 #[doc(alias = "ThisIsAnAlias")]
  53 pub enum WhoLetTheDogOut {
  54     /// Woof!
  55     Woof,
  56     /// Meoooooooow...
  57     Meow,
  58 }
  59
  60 /// Who doesn't love to wrap a `format!` call?
  61 pub fn some_more_function<T: fmt::Debug>(t: &T) -> String {
  62     format!("{:?}", t)
  63 }
  64
  65 /// Woohoo! A trait!
  66 pub trait AnotherOne {
  67     /// Some func 3.
  68     fn func3();
  69
  70     /// Some func 1.
  71     fn func1();
  72
  73     fn another();
  74     fn why_not();
  75
  76     /// Some func 2.
  77     fn func2();
  78
  79     fn hello();
  80 }
  81
  82 /// ```compile_fail
  83 /// whatever
  84 /// ```
  85 ///
  86 /// Check for "i" signs in lists!
  87 ///
  88 /// 1. elem 1
  89 /// 2. test 1
  90 ///    ```compile_fail
  91 ///    fn foo() {}
  92 ///    ```
  93 /// 3. elem 3
  94 /// 4. ```ignore (it's a test)
  95 ///    fn foo() {}
  96 ///    ```
  97 /// 5. elem 5
  98 ///
  99 /// Final one:
 100 ///
 101 /// ```ignore (still a test)
 102 /// let x = 12;
 103 /// ```
 104 pub fn check_list_code_block() {}
 105
 106 /// a thing with a label
 107 #[deprecated(since = "1.0.0", note = "text why this deprecated")]
 108 #[doc(cfg(unix))]
 109 pub fn replaced_function() {}
 110
 111 /// Some doc with `code`!
 112 pub enum AnEnum {
 113     WithVariants { and: usize, sub: usize, variants: usize },
 114 }
 115
 116 #[doc(keyword = "CookieMonster")]
 117 /// Some keyword.
 118 pub mod keyword {}
 119
 120 /// Just some type alias.
 121 pub type SomeType = u32;
 122
 123 pub mod huge_amount_of_consts {
 124     include!(concat!(env!("OUT_DIR"), "/huge_amount_of_consts.rs"));
 125 }
 126
 127 /// Very long code text `hereIgoWithLongTextBecauseWhyNotAndWhyWouldntI`.
 128 pub mod long_code_block {}
 129
 130 #[macro_export]
 131 macro_rules! repro {
 132     () => {};
 133 }
 134
 135 pub use crate::repro as repro2;
 136
 137 /// # Top-doc Prose title
 138 ///
 139 /// Text below title.
 140 ///
 141 /// ## Top-doc Prose sub-heading
 142 ///
 143 /// Text below sub-heading.
 144 ///
 145 /// ### Top-doc Prose sub-sub-heading
 146 ///
 147 /// Text below sub-sub-heading
 148 pub struct HeavilyDocumentedStruct {
 149     /// # Title for field
 150     /// ## Sub-heading for field
 151     pub nothing: (),
 152 }
 153
 154 /// # Title for struct impl doc
 155 ///
 156 /// Text below heading.
 157 ///
 158 /// ## Sub-heading for struct impl doc
 159 ///
 160 /// Text below sub-heading.
 161 ///
 162 /// ### Sub-sub-heading for struct impl doc
 163 ///
 164 /// Text below sub-sub-heading.
 165 ///
 166 impl HeavilyDocumentedStruct {
 167     /// # Title for struct impl-item doc
 168     /// Text below title.
 169     /// ## Sub-heading for struct impl-item doc
 170     /// Text below sub-heading.
 171     /// ### Sub-sub-heading for struct impl-item doc
 172     /// Text below sub-sub-heading.
 173     pub fn do_nothing() {}
 174 }
 175
 176 /// # Top-doc Prose title
 177 ///
 178 /// Text below title.
 179 ///
 180 /// ## Top-doc Prose sub-heading
 181 ///
 182 /// Text below sub-heading.
 183 ///
 184 /// ### Top-doc Prose sub-sub-heading
 185 ///
 186 /// Text below sub-sub-heading
 187 pub enum HeavilyDocumentedEnum {
 188     /// # None prose title
 189     /// ## None prose sub-heading
 190     None,
 191     /// # Wrapped prose title
 192     /// ## Wrapped prose sub-heading
 193     Wrapped(
 194         /// # Wrapped.0 prose title
 195         /// ## Wrapped.0 prose sub-heading
 196         String,
 197         String,
 198     ),
 199     Structy {
 200         /// # Structy prose title
 201         /// ## Structy prose sub-heading
 202         alpha: String,
 203         beta: String,
 204     },
 205 }
 206
 207 /// # Title for enum impl doc
 208 ///
 209 /// Text below heading.
 210 ///
 211 /// ## Sub-heading for enum impl doc
 212 ///
 213 /// Text below sub-heading.
 214 ///
 215 /// ### Sub-sub-heading for enum impl doc
 216 ///
 217 /// Text below sub-sub-heading.
 218 ///
 219 impl HeavilyDocumentedEnum {
 220     /// # Title for enum impl-item doc
 221     /// Text below title.
 222     /// ## Sub-heading for enum impl-item doc
 223     /// Text below sub-heading.
 224     /// ### Sub-sub-heading for enum impl-item doc
 225     /// Text below sub-sub-heading.
 226     pub fn do_nothing() {}
 227 }
 228
 229 /// # Top-doc prose title
 230 ///
 231 /// Text below heading.
 232 ///
 233 /// ## Top-doc prose sub-heading
 234 ///
 235 /// Text below heading.
 236 pub union HeavilyDocumentedUnion {
 237     /// # Title for union variant
 238     /// ## Sub-heading for union variant
 239     pub nothing: (),
 240     pub something: f32,
 241 }
 242
 243 /// # Title for union impl doc
 244 /// ## Sub-heading for union impl doc
 245 impl HeavilyDocumentedUnion {
 246     /// # Title for union impl-item doc
 247     /// ## Sub-heading for union impl-item doc
 248     pub fn do_nothing() {}
 249 }
 250
 251 /// # Top-doc prose title
 252 ///
 253 /// Text below heading.
 254 ///
 255 /// ## Top-doc prose sub-heading
 256 ///
 257 /// Text below heading.
 258 #[macro_export]
 259 macro_rules! heavily_documented_macro {
 260     () => {};
 261 }