tests/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 /// Very long code text [`hereIgoWithLongTextBecauseWhyNotAndWhyWouldntI`][lnk].
 158 ///
 159 /// [lnk]: crate::long_code_block_link
 160 pub mod long_code_block_link {}
 161
 162 #[macro_export]
 163 macro_rules! repro {
 164     () => {};
 165 }
 166
 167 pub use crate::repro as repro2;
 168
 169 /// # Top-doc Prose title
 170 ///
 171 /// Text below title.
 172 ///
 173 /// ## Top-doc Prose sub-heading
 174 ///
 175 /// Text below sub-heading.
 176 ///
 177 /// ### Top-doc Prose sub-sub-heading
 178 ///
 179 /// Text below sub-sub-heading
 180 ///
 181 /// #### You know the drill.
 182 ///
 183 /// More text.
 184 pub struct HeavilyDocumentedStruct {
 185     /// # Title for field
 186     /// ## Sub-heading for field
 187     pub nothing: (),
 188 }
 189
 190 /// # Title for struct impl doc
 191 ///
 192 /// Text below heading.
 193 ///
 194 /// ## Sub-heading for struct impl doc
 195 ///
 196 /// Text below sub-heading.
 197 ///
 198 /// ### Sub-sub-heading for struct impl doc
 199 ///
 200 /// Text below sub-sub-heading.
 201 ///
 202 impl HeavilyDocumentedStruct {
 203     /// # Title for struct impl-item doc
 204     /// Text below title.
 205     /// ## Sub-heading for struct impl-item doc
 206     /// Text below sub-heading.
 207     /// ### Sub-sub-heading for struct impl-item doc
 208     /// Text below sub-sub-heading.
 209     pub fn do_nothing() {}
 210 }
 211
 212 /// # Top-doc Prose title
 213 ///
 214 /// Text below title.
 215 ///
 216 /// ## Top-doc Prose sub-heading
 217 ///
 218 /// Text below sub-heading.
 219 ///
 220 /// ### Top-doc Prose sub-sub-heading
 221 ///
 222 /// Text below sub-sub-heading
 223 pub enum HeavilyDocumentedEnum {
 224     /// # None prose title
 225     /// ## None prose sub-heading
 226     None,
 227     /// # Wrapped prose title
 228     /// ## Wrapped prose sub-heading
 229     Wrapped(
 230         /// # Wrapped.0 prose title
 231         /// ## Wrapped.0 prose sub-heading
 232         String,
 233         String,
 234     ),
 235     Structy {
 236         /// # Structy prose title
 237         /// ## Structy prose sub-heading
 238         alpha: String,
 239         beta: String,
 240     },
 241 }
 242
 243 /// # Title for enum impl doc
 244 ///
 245 /// Text below heading.
 246 ///
 247 /// ## Sub-heading for enum impl doc
 248 ///
 249 /// Text below sub-heading.
 250 ///
 251 /// ### Sub-sub-heading for enum impl doc
 252 ///
 253 /// Text below sub-sub-heading.
 254 ///
 255 impl HeavilyDocumentedEnum {
 256     /// # Title for enum impl-item doc
 257     /// Text below title.
 258     /// ## Sub-heading for enum impl-item doc
 259     /// Text below sub-heading.
 260     /// ### Sub-sub-heading for enum impl-item doc
 261     /// Text below sub-sub-heading.
 262     pub fn do_nothing() {}
 263 }
 264
 265 /// # Top-doc prose title
 266 ///
 267 /// Text below heading.
 268 ///
 269 /// ## Top-doc prose sub-heading
 270 ///
 271 /// Text below heading.
 272 pub union HeavilyDocumentedUnion {
 273     /// # Title for union variant
 274     /// ## Sub-heading for union variant
 275     pub nothing: (),
 276     pub something: f32,
 277 }
 278
 279 /// # Title for union impl doc
 280 /// ## Sub-heading for union impl doc
 281 impl HeavilyDocumentedUnion {
 282     /// # Title for union impl-item doc
 283     /// ## Sub-heading for union impl-item doc
 284     pub fn do_nothing() {}
 285 }
 286
 287 /// # Top-doc prose title
 288 ///
 289 /// Text below heading.
 290 ///
 291 /// ## Top-doc prose sub-heading
 292 ///
 293 /// Text below heading.
 294 #[macro_export]
 295 macro_rules! heavily_documented_macro {
 296     () => {};
 297 }
 298
 299 pub trait EmptyTrait1 {}
 300 pub trait EmptyTrait2 {}
 301 pub trait EmptyTrait3 {}
 302
 303 pub struct HasEmptyTraits{}
 304
 305 impl EmptyTrait1 for HasEmptyTraits {}
 306 impl EmptyTrait2 for HasEmptyTraits {}
 307 #[doc(cfg(feature = "some-feature"))]
 308 impl EmptyTrait3 for HasEmptyTraits {}
 309
 310 mod macros;
 311 pub use macros::*;
 312
 313 #[doc(alias = "AliasForTheStdReexport")]
 314 pub use ::std as TheStdReexport;
 315
 316 pub mod details {
 317     /// We check the appearance of the `<details>`/`<summary>` in here.
 318     ///
 319     /// ## Hello
 320     ///
 321     /// <details>
 322     /// <summary><h4>I'm a summary</h4></summary>
 323     /// <div>I'm the content of the details!</div>
 324     /// </details>
 325     pub struct Details;
 326
 327     impl Details {
 328         /// We check the appearance of the `<details>`/`<summary>` in here.
 329         ///
 330         /// ## Hello
 331         ///
 332         /// <details>
 333         /// <summary><h4>I'm a summary</h4></summary>
 334         /// <div>I'm the content of the details!</div>
 335         /// </details>
 336         pub fn method() {}
 337     }
 338 }
 339
 340 pub mod doc_block_table {
 341
 342     pub trait DocBlockTableTrait {
 343         fn foo();
 344     }
 345
 346     /// Struct doc.
 347     ///
 348     /// | header1                  | header2                  |
 349     /// |--------------------------|--------------------------|
 350     /// | Lorem Ipsum, Lorem Ipsum | Lorem Ipsum, Lorem Ipsum |
 351     /// | Lorem Ipsum, Lorem Ipsum | Lorem Ipsum, Lorem Ipsum |
 352     /// | Lorem Ipsum, Lorem Ipsum | Lorem Ipsum, Lorem Ipsum |
 353     /// | Lorem Ipsum, Lorem Ipsum | Lorem Ipsum, Lorem Ipsum |
 354     pub struct DocBlockTable {}
 355
 356     impl DocBlockTableTrait for DocBlockTable {
 357         /// Trait impl func doc for struct.
 358         ///
 359         /// | header1                  | header2                  |
 360         /// |--------------------------|--------------------------|
 361         /// | Lorem Ipsum, Lorem Ipsum | Lorem Ipsum, Lorem Ipsum |
 362         fn foo() {
 363             println!();
 364         }
 365     }
 366
 367 }
 368
 369 pub struct NotableStructWithLongName<R>(R);
 370
 371 impl<R: std::io::Read> NotableStructWithLongName<R> {
 372     pub fn create_an_iterator_from_read(r: R) -> NotableStructWithLongName<R> { Self(r) }
 373 }
 374
 375 impl<R: std::io::Read> std::iter::Iterator for NotableStructWithLongName<R> {
 376     type Item = ();
 377
 378     fn next(&mut self) -> Option<Self::Item> { () }
 379 }
 380
 381 pub trait TraitWithNoDocblocks {
 382     fn first_fn(&self);
 383     fn second_fn(&self);
 384 }
 385
 386 pub struct TypeWithNoDocblocks;
 387
 388 impl TypeWithNoDocblocks {
 389     fn x() -> Option<Self> {
 390         Some(Self)
 391     }
 392     fn y() -> Option<u32> {
 393         // code comment
 394         let t = Self::x()?;
 395         Some(0)
 396     }
 397 }
 398
 399 impl TypeWithNoDocblocks {
 400     pub fn first_fn(&self) {}
 401     pub fn second_fn<'a>(&'a self) {
 402         let x = 12;
 403         let y = "a";
 404         let z = false;
 405     }
 406 }
 407
 408 pub unsafe fn unsafe_fn() {}
 409
 410 pub fn safe_fn() {}
 411
 412 #[repr(C)]
 413 pub struct WithGenerics<T: TraitWithNoDocblocks, S = String, E = WhoLetTheDogOut, P = i8> {
 414     s: S,
 415     t: T,
 416     e: E,
 417     p: P,
 418 }
 419
 420 pub struct StructWithPublicUndocumentedFields {
 421     pub first: u32,
 422     pub second: u32,
 423 }
 424
 425 pub const CONST: u8 = 0;
 426
 427 pub trait TraitWithoutGenerics {
 428     const C: u8 = CONST;
 429     type T = SomeType;
 430
 431     fn foo();
 432 }
 433
 434 pub mod trait_members {
 435     pub trait TraitMembers {
 436         /// Some type
 437         type Type;
 438         /// Some function
 439         fn function();
 440         /// Some other function
 441         fn function2();
 442     }
 443     pub struct HasTrait;
 444     impl TraitMembers for HasTrait {
 445         type Type = u8;
 446         fn function() {}
 447         fn function2() {}
 448     }
 449 }
 450
 451 pub struct TypeWithImplDoc;
 452
 453 /// impl doc
 454 impl TypeWithImplDoc {
 455     /// fn doc
 456     pub fn test_fn() {}
 457 }
 458
 459 /// <sub id="codeblock-sub-1">
 460 ///
 461 /// ```
 462 /// one
 463 /// ```
 464 ///
 465 /// </sub>
 466 ///
 467 /// <sub id="codeblock-sub-3">
 468 ///
 469 /// ```
 470 /// one
 471 /// two
 472 /// three
 473 /// ```
 474 ///
 475 /// </sub>
 476 pub mod codeblock_sub {}
 477 pub mod search_results {
 478
 479     pub struct SearchResults {
 480         pub foo: i32,
 481     }
 482
 483     #[macro_export]
 484     macro_rules! foo {
 485         () => {};
 486     }
 487
 488 }