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.
This commit is contained in:
bunnie 2021-08-01 16:08:27 +08:00
parent e968798fff
commit 2714c9eb13
8 changed files with 51 additions and 2 deletions

View file

@ -1,5 +1,7 @@
#![cfg_attr(target_os = "none", no_std)] #![cfg_attr(target_os = "none", no_std)]
//! Detailed docs are parked under Structs/Engine25519 down below
/* /*
#[cfg(target_os = "none")] #[cfg(target_os = "none")]
pub use curve25519_dalek_hw::*; pub use curve25519_dalek_hw::*;
@ -16,6 +18,7 @@ use xous_ipc::Buffer;
static mut ENGINE_CB: Option<fn(JobResult)> = None; static mut ENGINE_CB: Option<fn(JobResult)> = None;
#[doc = include_str!("../README.md")]
pub struct Engine25519 { pub struct Engine25519 {
conn: CID, conn: CID,
cb_sid: Option<[u32; 4]>, cb_sid: Option<[u32; 4]>,

View file

@ -1,5 +1,7 @@
#![cfg_attr(target_os = "none", no_std)] #![cfg_attr(target_os = "none", no_std)]
//! Detailed docs are parked under Structs/Gam down below
pub mod api; pub mod api;
pub use api::*; pub use api::*;
@ -22,9 +24,12 @@ use num_traits::*;
use ime_plugin_api::ImefCallback; use ime_plugin_api::ImefCallback;
#[doc = include_str!("../README.md")]
#[derive(Debug)] #[derive(Debug)]
pub struct Gam { 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, conn: xous::CID,
/// A SID for callbacks from the GAM (e.g. redraw requests)
callback_sid: Option<xous::SID>, callback_sid: Option<xous::SID>,
} }
impl Gam { impl Gam {

View file

@ -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::api::*;
use crate::Gam; use crate::Gam;
use crate::{MsgForwarder, forwarding_thread}; use crate::{MsgForwarder, forwarding_thread};

View file

@ -1,3 +1,4 @@
//! The main API entry point is the `Modal` struct. Click into the struct for more details.
/* /*
design ideas design ideas
@ -67,6 +68,7 @@ use locales::t;
pub const MAX_ITEMS: usize = 8; 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)] #[derive(Debug, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]
pub struct ItemName(String::<64>); pub struct ItemName(String::<64>);
impl ItemName { impl ItemName {
@ -77,14 +79,16 @@ impl ItemName {
self.0.as_str().expect("couldn't convert item into string") self.0.as_str().expect("couldn't convert item into string")
} }
} }
#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone, Eq, PartialEq)] #[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone, Eq, PartialEq)]
pub struct TextEntryPayload(pub String::<256>); pub struct TextEntryPayload(pub String::<256>);
impl TextEntryPayload { impl TextEntryPayload {
pub fn new() -> Self { pub fn new() -> Self {
TextEntryPayload(String::<256>::new()) 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) { 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 { pub fn as_str(&self) -> &str {
self.0.as_str().expect("couldn't convert textentry string") self.0.as_str().expect("couldn't convert textentry string")

View file

@ -1,4 +1,5 @@
#![cfg_attr(all(target_os = "none", not(test)), no_std)] #![cfg_attr(all(target_os = "none", not(test)), no_std)]
//! Detailed docs are parked under Structs/RootKeys down below
pub mod api; pub mod api;
use api::*; use api::*;
@ -25,6 +26,7 @@ pub enum ImageType {
Kernel, Kernel,
} }
#[doc = include_str!("../README.md")]
#[derive(Debug)] // there is no confidential information in the external structure; it's safe to Debug it #[derive(Debug)] // there is no confidential information in the external structure; it's safe to Debug it
pub struct RootKeys { pub struct RootKeys {
conn: CID, conn: CID,

View file

@ -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 and network events, have yet to be implemented. However, they will likely end up
with a demo in this application first. 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: it in the services/shellchat/src/cmds/ directory:
```Rust ```Rust

View file

@ -1,6 +1,34 @@
#![cfg_attr(target_os = "none", no_std)] #![cfg_attr(target_os = "none", no_std)]
#![cfg_attr(target_os = "none", no_main)] #![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<Option<String::<1024>>, 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 log::info;
use core::fmt::Write; use core::fmt::Write;
@ -12,6 +40,7 @@ use xous_ipc::{String, Buffer};
use heapless::spsc::Queue; use heapless::spsc::Queue;
#[doc = include_str!("../README.md")]
mod cmds; mod cmds;
use cmds::*; use cmds::*;

View file

@ -1,5 +1,7 @@
#![cfg_attr(target_os = "none", no_std)] #![cfg_attr(target_os = "none", no_std)]
//! Detailed docs are parked under Structs/XousNames down below
pub mod api; pub mod api;
use core::fmt::Write; use core::fmt::Write;
@ -7,6 +9,7 @@ use api::Disconnect;
use xous_ipc::{String, Buffer}; use xous_ipc::{String, Buffer};
use num_traits::ToPrimitive; use num_traits::ToPrimitive;
#[doc = include_str!("../README.md")]
#[derive(Debug)] #[derive(Debug)]
pub struct XousNames { pub struct XousNames {
conn: xous::CID, conn: xous::CID,