Add READMEs and top-level intro doc comments

Cargo.toml

@@ -4,6 +4,9 @@ version = "0.1.0"
 edition = "2021"
 authors = ["NGnius (Graham) <ngniusness@gmail.com>"]
 description = "Music Playlist Scripting language (MPS)"
+license = "LGPL-2.1-only OR GPL-2.0-or-later"
+license-file = "LICENSE"
+readme = "README.md"
 
 [workspace]
 members = [

README.md

@@ -0,0 +1,9 @@
+# mps
+
+An MPS program which plays music.
+This doesn't do much yet, since mps-interpreter is still under construction.
+
+Future home of a MPS REPL for playing music ergonomically through a CLI.
+
+
+License: LGPL-2.1-only OR GPL-2.0-or-later

mps-interpreter/Cargo.toml

@@ -2,6 +2,9 @@
 name = "mps-interpreter"
 version = "0.1.0"
 edition = "2021"
+license = "LGPL-2.1-only OR GPL-2.0-or-later"
+license-file = "LICENSE"
+readme = "README.md"
 
 [dependencies]
 rusqlite = { version = "0.26.3" }

mps-interpreter/README.md

@@ -0,0 +1,33 @@
+# mps-interpreter
+
+All necessary components to interpret and run a MPS script.
+
+MpsInterpretor uses a non-standard Iterator implementation,
+so it is recommended to use MpsRunner to execute a script.
+Since MPS is centered around iterators, script execution is also done by iterating.
+
+MpsInterpretor is misspelt to emphasise that it behaves strangely:
+after every MPS statement, a None item is returned even when the script is not complete.
+MpsRunner wraps MpsInterpretor so that this behaviour is hidden when iterating.
+
+```rust
+use std::io::Cursor;
+use mps_interpreter::*;
+
+let cursor = Cursor::new(
+"files(folder=`~/Music/`, recursive=true)" // retrieve all files from Music folder
+);
+
+let interpreter = MpsRunner::with_stream(cursor);
+
+// warning: my library has ~3800 songs, so this outputs too much information to be useful.
+for result in interpreter {
+    match result {
+        Ok(item) => println!("Got song `{}` (file: `{}`)", item.title, item.filename),
+        Err(e) => panic!("Got error while executing: {}", e),
+    }
+}
+```
+
+
+License: LGPL-2.1-only OR GPL-2.0-or-later

mps-interpreter/src/lib.rs

@@ -1,3 +1,33 @@
+//! All necessary components to interpret and run a MPS script.
+//!
+//! MpsInterpretor uses a non-standard Iterator implementation,
+//! so it is recommended to use MpsRunner to execute a script.
+//! Since MPS is centered around iterators, script execution is also done by iterating.
+//!
+//! MpsInterpretor is misspelt to emphasise that it behaves strangely:
+//! after every MPS statement, a None item is returned even when the script is not complete.
+//! MpsRunner wraps MpsInterpretor so that this behaviour is hidden when iterating.
+//!
+//! ```
+//! use std::io::Cursor;
+//! use mps_interpreter::*;
+//!
+//! let cursor = Cursor::new(
+//! "files(folder=`~/Music/`, recursive=true)" // retrieve all files from Music folder
+//! );
+//!
+//! let interpreter = MpsRunner::with_stream(cursor);
+//!
+//! // warning: my library has ~3800 songs, so this outputs too much information to be useful.
+//! for result in interpreter {
+//!     match result {
+//!         Ok(item) => println!("Got song `{}` (file: `{}`)", item.title, item.filename),
+//!         Err(e) => panic!("Got error while executing: {}", e),
+//!     }
+//! }
+//! ```
+//!
+
 mod context;
 mod interpretor;
 pub mod lang;

mps-player/Cargo.toml

@@ -2,6 +2,9 @@
 name = "mps-player"
 version = "0.1.0"
 edition = "2021"
+license = "LGPL-2.1-only OR GPL-2.0-or-later"
+license-file = "LICENSE"
+readme = "README.md"
 
 [dependencies]
 rodio = { version = "^0.14"}

mps-player/README.md

@@ -0,0 +1,6 @@
+# mps-player
+
+An MPS playback library with support for Linux media controls (D-Bus).
+
+
+License: LGPL-2.1-only OR GPL-2.0-or-later

mps-player/src/lib.rs

@@ -1,3 +1,6 @@
+//! An MPS playback library with support for Linux media controls (D-Bus).
+//!
+
 mod controller;
 mod errors;
 pub(crate) mod os_controls;

src/main.rs

@@ -1,3 +1,8 @@
+//! An MPS program which plays music.
+//! This doesn't do much yet, since mps-interpreter is still under construction.
+//!
+//! Future home of a MPS REPL for playing music ergonomically through a CLI.
+//!
 use std::io;
 use mps_interpreter::MpsRunner;
 use mps_player::{MpsPlayer, PlaybackError, MpsController};