1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

#![allow(dead_code)]
#![allow(clippy::bool_assert_comparison)]

//! Simple Doxygen to Rustdoc translation.
//!
//! Provides a simple and straightforward API to translate _raw_ Doxygen comments to Rustdoc
//! comments. Purely experimental right now, maybe practical in a future?
//!
//! # Examples
//!
//! ```
//! use doxygen_rs::transform;
//!
//! let rustdoc = transform("@brief Example Doxygen brief");
//! assert_eq!(rustdoc, "Example Doxygen brief\n\n");
//! ```
//!
//! # Supported commands
//! See the [tracking issue](https://github.com/Techie-Pi/doxygen-rs/issues/1) for the exhaustive list
//!
//! And the following _flavours_ are soported:
//! * ``\brief``
//! * ``\\brief``
//! * ``@brief``
//!
//! # Inner workings
//!
//! When the [``transform``] function is called, 3 other functions are called:
//! 1. The input is parsed to a [`Vec`] of [`parser::Value`] ([`parser::parse_comment`])
//! 2. The values are used to generate an AST ([`ast::generate_ast`])
//! 3. The AST is used to generate the Rustdoc ([`generator::generate_rustdoc`])
//!
//! ``transform [parse_comment -> generate_ast -> generate_rustdoc]``

use crate::parser::StringType;

pub mod parser;
pub mod ast;
pub mod generator;
mod utils;

/// Transforms raw Doxygen comments to raw Rustdoc comments
///
/// # Examples
///
/// ```
/// use doxygen_rs::transform;
///
/// let rustdoc = transform("@brief Example Doxygen brief");
/// assert_eq!(rustdoc, "Example Doxygen brief\n\n");
/// ```
pub fn transform(input: &str) -> String {
    let parsed = parser::parse_comment(input);
    let ast = ast::generate_ast(parsed);
    generator::generate_rustdoc(ast)
}

pub fn transform_bindgen(input: &str) -> String {
    let mut file_data = vec![];
    let parsed = parser::parse_bindgen(input);

    for parsed_data in parsed {
        match parsed_data {
            StringType::Parsed(data) => {
                let ast = ast::generate_ast(data);
                let rustdoc = generator::generate_rustdoc(ast);
                let bindgen_doc = rustdoc.lines().map(|v| format!("#[doc = \"{}\"]\n", v.trim())).collect::<String>();
                file_data.push(bindgen_doc);
            },
            StringType::Raw(raw) => file_data.push(raw),
        }
    }

    file_data.join("\n")
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs;

    #[test]
    fn raw_transform() {
        const INPUT: &str = r#"
@brief Creates a new dog.

Creates a new Dog named `_name` with half of its maximum energy.

@param _name The dog's name.
@param[in] _test Test for In

@deprecated

@return a great thing
"#;

        const EXPECTED: &str = r#"**Warning!** This is deprecated!

Creates a new dog.

Creates a new Dog named `_name` with half of its maximum energy.

Returns:

* a great thing

# Arguments

* `_name` - The dog's name.
* `_test` - Test for In [Direction: In]

"#;
        assert_eq!(
            EXPECTED,
            transform(INPUT).as_str(),
        );
    }

    #[test]
    fn raw_transform_bindgen() {
        let file = fs::read_to_string("assets/tests/example-bindgen.rs").unwrap();
        let result = transform_bindgen(file.as_str());
        let _ = fs::remove_file("assets/tests/bindgen-transformed.rs");
        fs::write("assets/tests/bindgen-transformed.rs", result).unwrap();
    }

    #[test]
    fn transform_ctru_sys_bindings() {
        let file = fs::read_to_string("assets/tests/ctru-sys-bindings.rs").unwrap();
        let result = transform_bindgen(file.as_str());
        let _ = fs::remove_file("assets/tests/ctru-sys-bindings-transformed.rs");
        fs::write("assets/tests/ctru-sys-bindings-transformed.rs", result).unwrap();
    }
}