From 2714c9eb139c0851d07da5d0d05ce80c6da21853 Mon Sep 17 00:00:00 2001 From: bunnie Date: Sun, 1 Aug 2021 16:08:27 +0800 Subject: [PATCH] link in some READMEs so that rustdoc pulls them in also add some bread crumbs on the more user-facing APIs to help beginners out. Need to do a good spring cleaning of the rustdoc tree, though. looks pretty terrible as it is. --- services/engine-25519/src/lib.rs | 3 +++ services/gam/src/lib.rs | 5 +++++ services/gam/src/menu.rs | 2 ++ services/gam/src/modal.rs | 6 +++++- services/root-keys/src/lib.rs | 2 ++ services/shellchat/README.md | 3 ++- services/shellchat/src/main.rs | 29 +++++++++++++++++++++++++++++ services/xous-names/src/lib.rs | 3 +++ 8 files changed, 51 insertions(+), 2 deletions(-) diff --git a/services/engine-25519/src/lib.rs b/services/engine-25519/src/lib.rs index 046f57ed8..c8236236a 100644 --- a/services/engine-25519/src/lib.rs +++ b/services/engine-25519/src/lib.rs @@ -1,5 +1,7 @@ #![cfg_attr(target_os = "none", no_std)] +//! Detailed docs are parked under Structs/Engine25519 down below + /* #[cfg(target_os = "none")] pub use curve25519_dalek_hw::*; @@ -16,6 +18,7 @@ use xous_ipc::Buffer; static mut ENGINE_CB: Option = None; +#[doc = include_str!("../README.md")] pub struct Engine25519 { conn: CID, cb_sid: Option<[u32; 4]>, diff --git a/services/gam/src/lib.rs b/services/gam/src/lib.rs index 1f212e3bd..501a391e9 100644 --- a/services/gam/src/lib.rs +++ b/services/gam/src/lib.rs @@ -1,5 +1,7 @@ #![cfg_attr(target_os = "none", no_std)] +//! Detailed docs are parked under Structs/Gam down below + pub mod api; pub use api::*; @@ -22,9 +24,12 @@ use num_traits::*; use ime_plugin_api::ImefCallback; +#[doc = include_str!("../README.md")] #[derive(Debug)] pub struct Gam { + /// The Gam structure exists on the client-side. This is the connection ID to the GAM server, local to this client. conn: xous::CID, + /// A SID for callbacks from the GAM (e.g. redraw requests) callback_sid: Option, } impl Gam { diff --git a/services/gam/src/menu.rs b/services/gam/src/menu.rs index 224fa2376..3d4ae4934 100644 --- a/services/gam/src/menu.rs +++ b/services/gam/src/menu.rs @@ -1,3 +1,5 @@ +//! The main API entry point is the `Menu` struct. Click into the struct for more details. + use crate::api::*; use crate::Gam; use crate::{MsgForwarder, forwarding_thread}; diff --git a/services/gam/src/modal.rs b/services/gam/src/modal.rs index 76369a872..aa9c3abee 100644 --- a/services/gam/src/modal.rs +++ b/services/gam/src/modal.rs @@ -1,3 +1,4 @@ +//! The main API entry point is the `Modal` struct. Click into the struct for more details. /* design ideas @@ -67,6 +68,7 @@ use locales::t; pub const MAX_ITEMS: usize = 8; +/// We use a new type for item names, so that it's easy to resize this as needed. #[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)] pub struct ItemName(String::<64>); impl ItemName { @@ -77,14 +79,16 @@ impl ItemName { self.0.as_str().expect("couldn't convert item into string") } } + #[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone, Eq, PartialEq)] pub struct TextEntryPayload(pub String::<256>); impl TextEntryPayload { pub fn new() -> Self { TextEntryPayload(String::<256>::new()) } + /// Ensures that 0's are written to the storage of this struct, and not optimized out; important for password fields. pub fn volatile_clear(&mut self) { - self.0.volatile_clear(); // volatile_clear() ensures that 0's are written and not optimized out; important for password fields + self.0.volatile_clear(); } pub fn as_str(&self) -> &str { self.0.as_str().expect("couldn't convert textentry string") diff --git a/services/root-keys/src/lib.rs b/services/root-keys/src/lib.rs index 1ad377301..29ee5d4f5 100644 --- a/services/root-keys/src/lib.rs +++ b/services/root-keys/src/lib.rs @@ -1,4 +1,5 @@ #![cfg_attr(all(target_os = "none", not(test)), no_std)] +//! Detailed docs are parked under Structs/RootKeys down below pub mod api; use api::*; @@ -25,6 +26,7 @@ pub enum ImageType { Kernel, } +#[doc = include_str!("../README.md")] #[derive(Debug)] // there is no confidential information in the external structure; it's safe to Debug it pub struct RootKeys { conn: CID, diff --git a/services/shellchat/README.md b/services/shellchat/README.md index e5f57d42f..9bc111ed2 100644 --- a/services/shellchat/README.md +++ b/services/shellchat/README.md @@ -14,7 +14,8 @@ Other facilities for handling system-level messages, such as menu configurations and network events, have yet to be implemented. However, they will likely end up with a demo in this application first. -To make your own command, copy the `echo.rs` template or snag the one below, and put +To make your own command, copy the `ver.rs` template (for an example with argument parsing), +or snag the very simple echo template below, and put it in the services/shellchat/src/cmds/ directory: ```Rust diff --git a/services/shellchat/src/main.rs b/services/shellchat/src/main.rs index c0d84cb2e..f1aacf78f 100644 --- a/services/shellchat/src/main.rs +++ b/services/shellchat/src/main.rs @@ -1,6 +1,34 @@ #![cfg_attr(target_os = "none", no_std)] #![cfg_attr(target_os = "none", no_main)] +/*! Detailed docs are parked under Modules/cmds "Shell Chat" below + +To make your own command, copy the `ver.rs` template (for an example with argument parsing), +or snag the very simple echo template below, and put +it in the services/shellchat/src/cmds/ directory: + +```Rust +use crate::{ShellCmdApi, CommonEnv}; +use xous_ipc::String; + +#[derive(Debug)] +pub struct Echo { +} + +impl<'a> ShellCmdApi<'a> for Echo { + cmd_api!(echo); // inserts boilerplate for command API + + fn process(&mut self, args: String::<1024>, _env: &mut CommonEnv) -> Result>, xous::Error> { + Ok(Some(rest)) + } +} +``` + +Once you've added your command to the directory, go to the `cmds.rs` file, and follow +the four-step instructions embedded within the file, starting around line 40. + +Check for more detailed docs under Modules/cmds "Shell Chat" below +*/ use log::info; use core::fmt::Write; @@ -12,6 +40,7 @@ use xous_ipc::{String, Buffer}; use heapless::spsc::Queue; +#[doc = include_str!("../README.md")] mod cmds; use cmds::*; diff --git a/services/xous-names/src/lib.rs b/services/xous-names/src/lib.rs index cf674c100..c51ea61c3 100644 --- a/services/xous-names/src/lib.rs +++ b/services/xous-names/src/lib.rs @@ -1,5 +1,7 @@ #![cfg_attr(target_os = "none", no_std)] +//! Detailed docs are parked under Structs/XousNames down below + pub mod api; use core::fmt::Write; @@ -7,6 +9,7 @@ use api::Disconnect; use xous_ipc::{String, Buffer}; use num_traits::ToPrimitive; +#[doc = include_str!("../README.md")] #[derive(Debug)] pub struct XousNames { conn: xous::CID,