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