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

Improve docs

ctru-rs/src/lib.rs

@@ -17,7 +17,7 @@ static __stacksize__: usize = 2 * 1024 * 1024; // 2MB
 /// Call this somewhere to force Rust to link some required crates
 /// This is also a setup for some crate integration only available at runtime
 ///
-/// See https://github.com/rust-lang/rust/issues/47384
+/// See <https://github.com/rust-lang/rust/issues/47384>
 pub fn init() {
     linker_fix_3ds::init();
     pthread_3ds::init();

ctru-rs/src/services/fs.rs

@@ -91,7 +91,7 @@ pub struct Fs(());
 /// # Examples
 ///
 /// ```no_run
-/// use ctru::services::fs::Fs
+/// use ctru::services::fs::Fs;
 ///
 /// let fs = Fs::init().unwrap();
 /// let sdmc_archive = fs.sdmc().unwrap();
@@ -116,14 +116,11 @@ pub struct Archive {
 /// use std::io::prelude::*;
 /// use ctru::services::fs::{Fs, File};
 ///
-/// # fn foo() -> std::io::Result<()> {
 /// let fs = Fs::init()?;
 /// let sdmc = fs.sdmc()?;
 ///
 /// let mut file = File::create(&sdmc, "/foo.txt")?;
 /// file.write_all(b"Hello, world!")?;
-/// # Ok(())
-/// #}
 /// ```
 ///
 /// Read the contents of a file into a `String`::
@@ -132,7 +129,6 @@ pub struct Archive {
 /// use std::io::prelude::*;
 /// use ctru::services::fs::{Fs, File};
 ///
-/// # fn foo() -> std::io::Result<()> {
 /// let fs = Fs::init()?;
 /// let sdmc = fs.sdmc()?;
 ///
@@ -140,8 +136,6 @@ pub struct Archive {
 /// let mut contents = String::new();
 /// file.read_to_string(&mut contents)?;
 /// assert_eq!(contents, "Hello, world!");
-/// # Ok(())
-/// #}
 /// ```
 ///
 /// It can be more efficient to read the contents of a file with a buffered
@@ -152,7 +146,6 @@ pub struct Archive {
 /// use std::io::prelude::*;
 /// use ctru::services::fs::{Fs, File};
 ///
-/// # fn foo() -> std::io::Result<()> {
 /// let fs = Fs::init()?;
 /// let sdmc = fs.sdmc()?;
 ///
@@ -161,8 +154,6 @@ pub struct Archive {
 /// let mut contents = String::new();
 /// buf_reader.read_to_string(&mut contents)?;
 /// assert_eq!(contents, "Hello, world!");
-/// # Ok(())
-/// # }
 /// ```
 pub struct File {
     handle: u32,
@@ -206,7 +197,7 @@ pub struct Metadata {
 /// Opening a file to read:
 ///
 /// ```no_run
-/// use ctru::services::fs::OpenOptions;
+/// use ctru::services::fs::{Fs, OpenOptions};
 ///
 /// let fs = Fs::init().unwrap();
 /// let sdmc_archive = fs.sdmc().unwrap();
@@ -221,7 +212,7 @@ pub struct Metadata {
 /// doesn't exist:
 ///
 /// ```no_run
-/// use ctru::services::fs::OpenOptions;
+/// use ctru::services::fs::{Fs, OpenOptions};
 ///
 /// let fs = Fs::init().unwrap();
 /// let sdmc_archive = fs.sdmc().unwrap();
@@ -350,8 +341,8 @@ impl File {
     /// ```no_run
     /// use ctru::services::fs::{Fs, File};
     ///
-    /// let fs = Fs::init().unwrap()
-    /// let sdmc_archive = fs.sdmc().unwrap()
+    /// let fs = Fs::init().unwrap();
+    /// let sdmc_archive = fs.sdmc().unwrap();
     /// let mut f = File::open(&sdmc_archive, "/foo.txt").unwrap();
     /// ```
     pub fn open<P: AsRef<Path>>(arch: &Archive, path: P) -> IoResult<File> {
@@ -379,8 +370,8 @@ impl File {
     /// ```no_run
     /// use ctru::services::fs::{Fs, File};
     ///
-    /// let fs = Fs::init().unwrap()
-    /// let sdmc_archive = fs.sdmc().unwrap()
+    /// let fs = Fs::init().unwrap();
+    /// let sdmc_archive = fs.sdmc().unwrap();
     /// let mut f = File::create(&sdmc_archive, "/foo.txt").unwrap();
     /// ```
     pub fn create<P: AsRef<Path>>(arch: &Archive, path: P) -> IoResult<File> {

ctru-sys/bindgen.sh

@@ -7,7 +7,6 @@ bindgen "$DEVKITPRO/libctru/include/3ds.h" \
     --use-core \
     --distrust-clang-mangling \
     --must-use-type 'Result' \
-    --no-doc-comments \
     --no-layout-tests \
     --ctypes-prefix "::libc" \
     --no-prepend-enum-name \
@@ -29,3 +28,5 @@ bindgen "$DEVKITPRO/libctru/include/3ds.h" \
     -DARM11 \
     -D__3DS__ \
 > src/bindings.rs
+
+cargo run --bin docstring-to-rustdoc -- src/bindings.rs

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

@@ -0,0 +1,70 @@
+//! 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::{env, fs, io};
+use std::path::Path;
+
+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(())
+}