Merge pull request #75 from Techie-Pi/chore/improve-docs-v2

Further improve ``bindings.rs`` documentation

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["ctru-rs", "ctru-sys"]
+members = ["ctru-rs", "ctru-sys", "ctru-sys/docstring-to-rustdoc"]
 
 [patch.'https://github.com/Meziu/ctru-rs']
 # Make sure all dependencies use the local ctru-sys package

ctru-sys/bindgen.sh

@@ -29,4 +29,6 @@ bindgen "$DEVKITPRO/libctru/include/3ds.h" \
     -D__3DS__ \
 > src/bindings.rs
 
-cargo run --bin docstring-to-rustdoc -- src/bindings.rs
+cargo run --package docstring-to-rustdoc -- src/bindings.rs
+
+cargo fmt --all

ctru-sys/docstring-to-rustdoc/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "docstring-to-rustdoc"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+doxygen-rs = { git = "https://github.com/Techie-Pi/doxygen-rs.git", version = "0.2.2", rev = "573f483ad63ab4662650961998d3ed093a703983" }

ctru-sys/docstring-to-rustdoc/src/main.rs

@@ -0,0 +1,31 @@
+//! This script transforms _some_ Boxygen comments to Rustdoc format
+//!
+//! # Usage
+//!
+//! `cargo run --package docstring-to-rustdoc -- [location of the bindings.rs]`
+//! Example: `cargo run --package docstring-to-rustdoc -- src/bindings.rs`
+//!
+//! # Transformations
+//!
+//! Check [doxygen-rs docs](https://techie-pi.github.io/doxygen-rs/doxygen_rs/)
+
+use std::path::Path;
+use std::{env, fs, io};
+
+fn main() -> io::Result<()> {
+    let args: Vec<String> = env::args().collect();
+
+    let bindings_path = Path::new(args.get(1).expect("bindings.rs not provided in the args"));
+    let bindings = fs::read_to_string(bindings_path)?;
+
+    let parsed = doxygen_rs::transform_bindgen(bindings.as_str());
+
+    let old_bindings_path = bindings_path.to_str().unwrap().to_owned() + ".old";
+
+    // If something fails, the original bindings are available at ``bindings.rs.old``
+    fs::rename(bindings_path, &old_bindings_path)?;
+    fs::write(bindings_path, parsed)?;
+    fs::remove_file(&old_bindings_path)?;
+
+    Ok(())
+}

ctru-sys/src/bin/docstring-to-rustdoc.rs

@@ -1,67 +0,0 @@
-//! This script transforms _some_ Boxygen comments to Rustdoc format
-//!
-//! # Usage
-//!
-//! `cargo run --bin docstring-to-rustdoc -- [location of the bindings.rs]`
-//! Example: `cargo run --bin docstring-to-rustdoc -- src/bindings.rs`
-//!
-//! # Transformations
-//!
-//! The following are _completely_ removed, but _its contents are kept_:
-//! * `@brief`
-//! * `@ref`
-//! * `@note`
-//! * `@return`
-//! * `@sa`
-//! * `<`
-//! * `[out]` and `[in]`
-//!
-//! The followings are _partially_ transformed to Rustdoc format:
-//! * `@param`
-
-use std::path::Path;
-use std::{env, fs, io};
-
-fn main() -> io::Result<()> {
-    let args: Vec<String> = env::args().collect();
-
-    let bindings_path = Path::new(args.get(1).expect("bindings.rs not provided in the args"));
-    let bindings_string: String = fs::read_to_string(bindings_path)?;
-
-    let parsed = bindings_string
-        .lines()
-        .map(|v| {
-            // Only modify lines with the following structure: `` #[doc ... ] ``
-            if v.trim_start().starts_with("#[doc") && v.trim_end().ends_with(']') {
-                v.replace("@brief", "")
-                    // Example: ``@param offset Offset of the RomFS...`` -> ``- offset Offset of the RomFS...``
-                    // Will improve in the future
-                    .replace("@param", "* ")
-                    .replace("@ref", "")
-                    .replace("@note", "")
-                    .replace("@return", "")
-                    .replace("@sa", "")
-                    .replace("< ", "")
-                    // Remove things like ``@param[out]``
-                    .replace("[out]", "")
-                    .replace("[in]", "")
-                    // Trim start of the Rustdoc: ``...= " ...`` -> ``...= "...``
-                    .replace("= \" ", "= \"")
-                    // Double pass because _most_ annotations are at the start
-                    .replace("= \" ", "= \"")
-            } else {
-                String::from(v)
-            }
-        })
-        .map(|v| v + "\n")
-        .collect::<String>();
-
-    let old_bindings_path = bindings_path.to_str().unwrap().to_owned() + ".old";
-
-    // If something fails, the original bindings are available at ``bindings.rs.old``
-    fs::rename(bindings_path, &old_bindings_path)?;
-    fs::write(bindings_path, parsed)?;
-    fs::remove_file(&old_bindings_path)?;
-
-    Ok(())
-}