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