tools/lib/reference_doc/macro/derive-reference-doc-tests/src/lib.rs

// Copyright 2021 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Allow dead code to avoid annotating every field in the test structs
// with #[allow(dead_code)]
#![allow(dead_code)]

mod tests {
    use pretty_assertions::assert_eq;
    use reference_doc::{MarkdownReferenceDocGenerator, ReferenceDoc};
    use std::collections::HashMap;

    /// # Big picture
    ///
    /// A struct that is parsed to JSON.
    ///
    /// ## Top-level keys
    #[derive(ReferenceDoc)]
    struct ReferenceDocTest {
        /// This content describes str.
        ///
        /// # This heading will be indented by default
        str: Option<String>,

        /// This is a vector with overridden json type number.
        #[reference_doc(json_type = "number")]
        r#use: Vec<String>,

        /// This is a map!
        map: Option<HashMap<String, String>>,

        /// This will appear first when describing `objects`.
        #[reference_doc(recurse)]
        objects: Option<Vec<ReferenceDocTestObject1>>,

        /// More objects.
        #[reference_doc(recurse)]
        objects2: ReferenceDocTestObject2,

        /// A hidden bool. This field shall be skipped refdoc comments.
        #[reference_doc(skip = true)]
        please_skip: bool,
    }

    /// This will appear after describing the fields.
    #[derive(ReferenceDoc)]
    #[reference_doc(top_level_doc_after_fields)]
    struct ReferenceDocTestObject1 {
        /// This will appear when documenting this field specifically.
        ///
        /// # A super indented header!
        an_int: i32,
    }

    /// This should display fields as a list.
    #[derive(ReferenceDoc)]
    #[reference_doc(fields_as = "list")]
    struct ReferenceDocTestObject2 {
        /// It's a string, but it can take the following values:
        /// - "0": zero things
        /// - "1": one thing!
        val: String,

        /// An enum.
        val2: Option<ReferenceDocTestEnum>,
    }

    enum ReferenceDocTestEnum {
        Foo,
        Bar,
    }

    /// # Works with generic
    ///
    /// This object contains generics and works fine.
    #[derive(ReferenceDoc)]
    struct TopLevelGeneric<D: MarkdownReferenceDocGenerator> {
        /// A generic value.
        #[reference_doc(recurse)]
        val: D,
    }

    #[test]
    fn test_reference_doc() {
        assert_eq!(
            &ReferenceDocTest::get_reference_doc_markdown(),
            r#"# Big picture

A struct that is parsed to JSON.

## Top-level keys

### `str` {#str}

_`string` (optional)_

This content describes str.

#### This heading will be indented by default

### `use` {#use}

_array of `number`_

This is a vector with overridden json type number.

### `map` {#map}

_`object` (optional)_

This is a map!

### `objects` {#objects}

_array of `object` (optional)_

This will appear first when describing `objects`.

#### `an_int` {#an_int}

_`number`_

This will appear when documenting this field specifically.

##### A super indented header!


This will appear after describing the fields.



### `objects2` {#objects2}

_`object`_

More objects.

This should display fields as a list.

- `val`: (_`string`_) It's a string, but it can take the following values:
    - "0": zero things
    - "1": one thing!
- `val2`: (_optional `string`_) An enum.


"#,
        );
    }

    #[test]
    fn test_reference_doc_with_generics() {
        assert_eq!(
            &TopLevelGeneric::<ReferenceDocTestObject1>::get_reference_doc_markdown(),
            r#"# Works with generic

This object contains generics and works fine.

## `val` {#val}

_`object`_

A generic value.

### `an_int` {#an_int}

_`number`_

This will appear when documenting this field specifically.

#### A super indented header!


This will appear after describing the fields.



"#
        );
    }
}