Revamp README and HACKING to be more fleshed out and up-to-date

HACKING.md

@@ -1,26 +1,30 @@
-This project is written in rust. For any unfamiliar with how that works the following should help:
+This project is written in [Rust](https://www.rust-lang.org/). For any
+unfamiliar with how that works the following should help:
 
-To build you'll want a rust implementation for your laptop/device you are testing on.
+# Building
 
-https://wiki.archlinux.org/title/rust has some good guidelines for getting that sorted. but mostly boils down
+To build you'll want a Rust implementation for your laptop/device you are testing on.
-to install rustup from the rustup package (if you're on arch) and use:
 
-rustup default stable
+The [Arch wiki article](https://wiki.archlinux.org/title/rust) has some good
+guidelines for getting that sorted, but mostly boils down to installing
+`rustup` from the `rustup` package (if you're on Arch) and running `rustup
+default stable` to get an initial toolchain.
 
-to get an initial toolchain, etc.
+Once you have that and `cargo` is in your path, to build the project you can
+use `cargo build`. To run tests you can use `cargo test`.
 
-Once you have that and cargo is in your path, to build and run this project use the following:
+Note that Arch also provides the `rust` package for a system-managed Rust
+installation, which is also sufficient for development on this project.
 
-To build:
+# Developing
 
-cargo build
+As far as IDEs go, Visual Studio Code works pretty well for giving errors about
+things you are changing and has plugins for vim mode, etc. if you are used to
+those keybindings. Most/all IDEs that work with language servers should do that
+fine though.
 
-To run:
+For VS Code, these extensions help: `rust` and `rust-analyzer`.
 
-cargo run
+Before committing code, please run `cargo fmt` to make sure that your code
-
+matches the preferred code style, and `cargo clippy` can help with common
-As far as IDEs go I find Visual Studio Code works pretty well for giving errors about things you
+mistakes and idiomatic code.
-are changing and has plugins for vim mode, etc. if you are used to those keybindings. Most/all
-IDEs that work with language servers should do that fine though.
-
-For VS Code I use these extensions to help: rust and rust-analyzer

README.md

@@ -1,23 +1,35 @@
-This is the SteamOS Manager.
+# SteamOS Manager
 
-It is a small daemon that's sole purpose is to give Steam something with a DBus
+SteamOS Manager is a small daemon whose primary purpose is to give Steam
-api that runs as root and can do things to the system without having to have
+something with a DBus API that runs as root and can do things to the system
-hard coded paths and DBus apis in the Steam client itself.
+without having to have hard coded paths and DBus API in the Steam client
+itself. It also runs some background tasks, as well as giving a centralized
+daemon for managing some user-context tasks that aren't particularly related to
+Steam itself.
 
-It is a mostly thin wrapper around other scripts and DBus apis that provides feedback for
+Many of these root tasks are implemented as athin wrapper around other scripts.
-each DBus method it implements.
+This lets the DBus APIs invoke the scripts as a privileged but non-root user
+and provides feedback for each DBus method it implements.
 
-How it works:
+## How it works
 
-The SteamOS Manager runs as root and exposes a DBus api on the system bus.
+The SteamOS Manager runs as `root` and exposes a DBus API on the system bus.
-Another instance runs as deck user and exposes a DBus api on the session bus with
+Another instance runs as `deck` and exposes a DBus API on the session bus with
-a few extra methods. These methods run directly in the user daemon as deck user. All
+a few extra methods that handle tasks that are user-specific. These methods run
-other apis forward to the root daemon via it's DBus api.
+directly in the user daemon as that user. All other APIs are relayed to the
+root daemon via its DBus API.
 
-To add a new method:
+## To add a new method
 
-To add a new method that doesn't require root privileges add it to the user daemon's DBus api
+To add a new method that doesn't require root privileges, add it to the user
-directly.
+daemon's DBus API directly. This is implemented in `src/manager/usr.rs`
 
-To add a new method that does require root privileges add it to the root daemon's DBus api and it will
+To add a new method that does require root privileges, add it to the root
-be exposed automatically in the user daemon.
+daemon's DBus API in `src/manager/root.rs`, update the proxy implementation in
+`src/proxy.rs`, and add a relay method in `src/manager/user.rs`.
+
+In both cases, make sure to add the new API to the XML schema. The methods are
+test automatically to match the schema, so these tests will fail if they don't.
+
+Further, if this is the first change made to the schema since the last tag,
+increment the API version number in `src/lib.rs`.