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 #![doc(html_playground_url="https://play.rust-lang.org/")]
   4
   5 #![crate_name = "test_docs"]
   6 #![feature(rustdoc_internals)]
   7 #![feature(doc_cfg)]
   8 #![feature(associated_type_defaults)]
   9
  10 /*!
  11 Enable the feature <span class="stab portability"><code>some-feature</code></span> to enjoy
  12 this crate even more!
  13 Enable the feature <span class="stab portability"><code>some-feature</code></span> to enjoy
  14 this crate even more!
  15 Enable the feature <span class="stab portability"><code>some-feature</code></span> to enjoy
  16 this crate even more!
  17
  18 Also, stop using `bar` as it's <span class="stab deprecated" title="">deprecated</span>.
  19 Also, stop using `bar` as it's <span class="stab deprecated" title="">deprecated</span>.
  20 Also, stop using `bar` as it's <span class="stab deprecated" title="">deprecated</span>.
  21
  22 Finally, you can use `quz` only on <span class="stab portability"><code>Unix or x86-64</code>
  23 </span>.
  24 Finally, you can use `quz` only on <span class="stab portability"><code>Unix or x86-64</code>
  25 </span>.
  26 */
  27
  28 use std::convert::AsRef;
  29 use std::fmt;
  30
  31 /// Basic function with some code examples:
  32 ///
  33 /// ```
  34 /// println!("nothing fancy");
  35 /// println!("but with two lines!");
  36 /// ```
  37 ///
  38 /// A failing to compile one:
  39 ///
  40 /// ```compile_fail
  41 /// println!("where did my argument {} go? :'(");
  42 /// ```
  43 ///
  44 /// An ignored one:
  45 ///
  46 /// ```ignore (it's a test)
  47 /// Let's say I'm just some text will ya?
  48 /// ```
  49 ///
  50 /// A failing to run one:
  51 ///
  52 /// ```should_panic
  53 /// panic!("tadam");
  54 /// ```
  55 ///
  56 /// An inlined `code`!
  57 pub fn foo() {}
  58
  59 /// Just a normal struct.
  60 pub struct Foo;
  61
  62 impl Foo {
  63     #[must_use]
  64     pub fn must_use(&self) -> bool {
  65         true
  66     }
  67 }
  68
  69 impl AsRef<str> for Foo {
  70     fn as_ref(&self) -> &str {
  71         "hello"
  72     }
  73 }
  74
  75 /// Just a normal enum.
  76 ///
  77 /// # title!
  78 #[doc(alias = "ThisIsAnAlias")]
  79 #[non_exhaustive]
  80 pub enum WhoLetTheDogOut {
  81     /// Woof!
  82     Woof,
  83     /// Meoooooooow...
  84     Meow,
  85 }
  86
  87 /// Who doesn't love to wrap a `format!` call?
  88 pub fn some_more_function<T: fmt::Debug>(t: &T) -> String {
  89     format!("{:?}", t)
  90 }
  91
  92 /// Woohoo! A trait!
  93 pub trait AnotherOne {
  94     /// Some func 3.
  95     fn func3();
  96
  97     /// Some func 1.
  98     fn func1();
  99
 100     fn another();
 101     fn why_not();
 102
 103     /// Some func 2.
 104     fn func2();
 105
 106     fn hello();
 107 }
 108
 109 /// ```compile_fail
 110 /// whatever
 111 /// ```
 112 ///
 113 /// Check for "i" signs in lists!
 114 ///
 115 /// 1. elem 1
 116 /// 2. test 1
 117 ///    ```compile_fail
 118 ///    fn foo() {}
 119 ///    ```
 120 /// 3. elem 3
 121 /// 4. ```ignore (it's a test)
 122 ///    fn foo() {}
 123 ///    ```
 124 /// 5. elem 5
 125 ///
 126 /// Final one:
 127 ///
 128 /// ```ignore (still a test)
 129 /// let x = 12;
 130 /// ```
 131 pub fn check_list_code_block() {}
 132
 133 /// a thing with a label
 134 #[deprecated(since = "1.0.0", note = "text why this deprecated")]
 135 #[doc(cfg(unix))]
 136 pub fn replaced_function() {}
 137
 138 /// Some doc with `code`!
 139 pub enum AnEnum {
 140     WithVariants { and: usize, sub: usize, variants: usize },
 141 }
 142
 143 #[doc(keyword = "CookieMonster")]
 144 /// Some keyword.
 145 pub mod keyword {}
 146
 147 /// Just some type alias.
 148 pub type SomeType = u32;
 149
 150 pub mod huge_amount_of_consts {
 151     include!(concat!(env!("OUT_DIR"), "/huge_amount_of_consts.rs"));
 152 }
 153
 154 /// Very long code text `hereIgoWithLongTextBecauseWhyNotAndWhyWouldntI`.
 155 pub mod long_code_block {}
 156
 157 #[macro_export]
 158 macro_rules! repro {
 159     () => {};
 160 }
 161
 162 pub use crate::repro as repro2;
 163
 164 /// # Top-doc Prose title
 165 ///
 166 /// Text below title.
 167 ///
 168 /// ## Top-doc Prose sub-heading
 169 ///
 170 /// Text below sub-heading.
 171 ///
 172 /// ### Top-doc Prose sub-sub-heading
 173 ///
 174 /// Text below sub-sub-heading
 175 ///
 176 /// #### You know the drill.
 177 ///
 178 /// More text.
 179 pub struct HeavilyDocumentedStruct {
 180     /// # Title for field
 181     /// ## Sub-heading for field
 182     pub nothing: (),
 183 }
 184
 185 /// # Title for struct impl doc
 186 ///
 187 /// Text below heading.
 188 ///
 189 /// ## Sub-heading for struct impl doc
 190 ///
 191 /// Text below sub-heading.
 192 ///
 193 /// ### Sub-sub-heading for struct impl doc
 194 ///
 195 /// Text below sub-sub-heading.
 196 ///
 197 impl HeavilyDocumentedStruct {
 198     /// # Title for struct impl-item doc
 199     /// Text below title.
 200     /// ## Sub-heading for struct impl-item doc
 201     /// Text below sub-heading.
 202     /// ### Sub-sub-heading for struct impl-item doc
 203     /// Text below sub-sub-heading.
 204     pub fn do_nothing() {}
 205 }
 206
 207 /// # Top-doc Prose title
 208 ///
 209 /// Text below title.
 210 ///
 211 /// ## Top-doc Prose sub-heading
 212 ///
 213 /// Text below sub-heading.
 214 ///
 215 /// ### Top-doc Prose sub-sub-heading
 216 ///
 217 /// Text below sub-sub-heading
 218 pub enum HeavilyDocumentedEnum {
 219     /// # None prose title
 220     /// ## None prose sub-heading
 221     None,
 222     /// # Wrapped prose title
 223     /// ## Wrapped prose sub-heading
 224     Wrapped(
 225         /// # Wrapped.0 prose title
 226         /// ## Wrapped.0 prose sub-heading
 227         String,
 228         String,
 229     ),
 230     Structy {
 231         /// # Structy prose title
 232         /// ## Structy prose sub-heading
 233         alpha: String,
 234         beta: String,
 235     },
 236 }
 237
 238 /// # Title for enum impl doc
 239 ///
 240 /// Text below heading.
 241 ///
 242 /// ## Sub-heading for enum impl doc
 243 ///
 244 /// Text below sub-heading.
 245 ///
 246 /// ### Sub-sub-heading for enum impl doc
 247 ///
 248 /// Text below sub-sub-heading.
 249 ///
 250 impl HeavilyDocumentedEnum {
 251     /// # Title for enum impl-item doc
 252     /// Text below title.
 253     /// ## Sub-heading for enum impl-item doc
 254     /// Text below sub-heading.
 255     /// ### Sub-sub-heading for enum impl-item doc
 256     /// Text below sub-sub-heading.
 257     pub fn do_nothing() {}
 258 }
 259
 260 /// # Top-doc prose title
 261 ///
 262 /// Text below heading.
 263 ///
 264 /// ## Top-doc prose sub-heading
 265 ///
 266 /// Text below heading.
 267 pub union HeavilyDocumentedUnion {
 268     /// # Title for union variant
 269     /// ## Sub-heading for union variant
 270     pub nothing: (),
 271     pub something: f32,
 272 }
 273
 274 /// # Title for union impl doc
 275 /// ## Sub-heading for union impl doc
 276 impl HeavilyDocumentedUnion {
 277     /// # Title for union impl-item doc
 278     /// ## Sub-heading for union impl-item doc
 279     pub fn do_nothing() {}
 280 }
 281
 282 /// # Top-doc prose title
 283 ///
 284 /// Text below heading.
 285 ///
 286 /// ## Top-doc prose sub-heading
 287 ///
 288 /// Text below heading.
 289 #[macro_export]
 290 macro_rules! heavily_documented_macro {
 291     () => {};
 292 }
 293
 294 pub trait EmptyTrait1 {}
 295 pub trait EmptyTrait2 {}
 296 pub trait EmptyTrait3 {}
 297
 298 pub struct HasEmptyTraits{}
 299
 300 impl EmptyTrait1 for HasEmptyTraits {}
 301 impl EmptyTrait2 for HasEmptyTraits {}
 302 #[doc(cfg(feature = "some-feature"))]
 303 impl EmptyTrait3 for HasEmptyTraits {}
 304
 305 mod macros;
 306 pub use macros::*;
 307
 308 #[doc(alias = "AliasForTheStdReexport")]
 309 pub use ::std as TheStdReexport;
 310
 311 pub mod details {
 312     /// We check the appearance of the `<details>`/`<summary>` in here.
 313     ///
 314     /// ## Hello
 315     ///
 316     /// <details>
 317     /// <summary><h4>I'm a summary</h4></summary>
 318     /// <div>I'm the content of the details!</div>
 319     /// </details>
 320     pub struct Details;
 321
 322     impl Details {
 323         /// We check the appearance of the `<details>`/`<summary>` in here.
 324         ///
 325         /// ## Hello
 326         ///
 327         /// <details>
 328         /// <summary><h4>I'm a summary</h4></summary>
 329         /// <div>I'm the content of the details!</div>
 330         /// </details>
 331         pub fn method() {}
 332     }
 333 }
 334
 335 pub mod doc_block_table {
 336
 337     pub trait DocBlockTableTrait {
 338         fn func();
 339     }
 340
 341     /// Struct doc.
 342     ///
 343     /// | header1                  | header2                  |
 344     /// |--------------------------|--------------------------|
 345     /// | Lorem Ipsum, Lorem Ipsum | Lorem Ipsum, Lorem Ipsum |
 346     pub struct DocBlockTable {}
 347
 348     impl DocBlockTableTrait for DocBlockTable {
 349         /// Trait impl func doc for struct.
 350         ///
 351         /// | header1                  | header2                  |
 352         /// |--------------------------|--------------------------|
 353         /// | Lorem Ipsum, Lorem Ipsum | Lorem Ipsum, Lorem Ipsum |
 354         fn func() {
 355             println!();
 356         }
 357     }
 358
 359 }
 360
 361 pub struct NotableStructWithLongName<R>(R);
 362
 363 impl<R: std::io::Read> NotableStructWithLongName<R> {
 364     pub fn create_an_iterator_from_read(r: R) -> NotableStructWithLongName<R> { Self(r) }
 365 }
 366
 367 impl<R: std::io::Read> std::iter::Iterator for NotableStructWithLongName<R> {
 368     type Item = ();
 369
 370     fn next(&mut self) -> Option<Self::Item> { () }
 371 }
 372
 373 pub trait TraitWithNoDocblocks {
 374     fn first_fn(&self);
 375     fn second_fn(&self);
 376 }
 377
 378 pub struct TypeWithNoDocblocks;
 379
 380 impl TypeWithNoDocblocks {
 381     fn x() -> Option<Self> {
 382         Some(Self)
 383     }
 384     fn y() -> Option<u32> {
 385         // code comment
 386         let t = Self::x()?;
 387         Some(0)
 388     }
 389 }
 390
 391 impl TypeWithNoDocblocks {
 392     pub fn first_fn(&self) {}
 393     pub fn second_fn<'a>(&'a self) {
 394         let x = 12;
 395         let y = "a";
 396         let z = false;
 397     }
 398 }
 399
 400 pub unsafe fn unsafe_fn() {}
 401
 402 pub fn safe_fn() {}
 403
 404 #[repr(C)]
 405 pub struct WithGenerics<T: TraitWithNoDocblocks, S = String, E = WhoLetTheDogOut, P = i8> {
 406     s: S,
 407     t: T,
 408     e: E,
 409     p: P,
 410 }
 411
 412 pub struct StructWithPublicUndocumentedFields {
 413     pub first: u32,
 414     pub second: u32,
 415 }
 416
 417 pub const CONST: u8 = 0;
 418
 419 pub trait TraitWithoutGenerics {
 420     const C: u8 = CONST;
 421     type T = SomeType;
 422
 423     fn foo();
 424 }
 425
 426 pub mod trait_members {
 427     pub trait TraitMembers {
 428         /// Some type
 429         type Type;
 430         /// Some function
 431         fn function();
 432         /// Some other function
 433         fn function2();
 434     }
 435     pub struct HasTrait;
 436     impl TraitMembers for HasTrait {
 437         type Type = u8;
 438         fn function() {}
 439         fn function2() {}
 440     }
 441 }