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)]
//! 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<fn(JobResult)> = None;
#[doc = include_str!("../README.md")]
pub struct Engine25519 {
conn: CID,
cb_sid: Option<[u32; 4]>,

View file

@ -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<xous::SID>,
}
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::Gam;
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
@ -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")

View file

@ -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,

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
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

View file

@ -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<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 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::*;

View file

@ -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,