Improve the documentation for the settings (#74)

Now all the features of the derive macro are documented. There is also
full documentation describing the relationship between the settings gui
and the settings map in the settings module.

asr-derive/src/lib.rs

@@ -3,10 +3,20 @@ use proc_macro::TokenStream;
 use quote::{quote, quote_spanned};
 use syn::{spanned::Spanned, Data, DeriveInput, Expr, ExprLit, Lit, Meta};
 
+// FIXME: https://github.com/rust-lang/rust/issues/117463
+#[allow(rustdoc::redundant_explicit_links)]
 /// Implements the `Gui` trait for a struct that allows you to register its
 /// fields as settings widgets and returns the struct with the user's settings
 /// applied.
 ///
+/// The name of each field is used as the key for the setting for storing it in
+/// the global settings map and looking up the current value.
+///
+/// The first paragraph in the doc comment of each field is used as the
+/// description of the setting. The rest of the doc comment is used as the
+/// tooltip. If there is no doc comment, the name of the field is used as the
+/// description (in title case).
+///
 /// # Example
 ///
 /// ```no_run
@@ -31,6 +41,30 @@ use syn::{spanned::Spanned, Data, DeriveInput, Expr, ExprLit, Lit, Meta};
 ///    // Do something with the settings.
 /// }
 /// ```
+///
+/// # Attributes
+///
+/// The default value of the setting normally matches the
+/// [`Default`](core::default::Default) trait. If you want to specify a
+/// different default you can specify it like so:
+///
+/// ```no_run
+/// # struct Settings {
+/// #[default = true]
+/// foo: bool,
+/// # }
+/// ```
+///
+/// The heading level of a title can be specified to form a hierarchy. The top
+/// level titles use a heading level of 0. It is also the default heading level.
+/// You can specify a different heading level like so:
+///
+/// ```no_run
+/// # struct Settings {
+/// #[heading_level = 2]
+/// _title: Title,
+/// # }
+/// ```
 #[proc_macro_derive(Gui, attributes(default, heading_level))]
 pub fn settings_macro(input: TokenStream) -> TokenStream {
     let ast: DeriveInput = syn::parse(input).unwrap();

src/runtime/settings/mod.rs

@@ -1,4 +1,58 @@
 //! Support for interacting with the settings of the auto splitter.
+//!
+//! # Overview
+//!
+//! Settings consist of two parts. One part is the settings [`Gui`], that is
+//! used to let the user configure the settings. The other part is the settings
+//! values that are actually stored in the splits file. Those settings don't
+//! necessarily correlate entirely with the settings [`Gui`], because the stored
+//! splits might either be from a different version of the auto splitter or
+//! contain additional information such as the version of the settings, that the
+//! user doesn't necessarily directly interact with. These stored settings are
+//! available as the global settings [`Map`], which can be loaded, modified and
+//! stored freely. The keys used for the settings widgets directly correlate
+//! with the keys used in the settings [`Map`]. Any changes in the settings
+//! [`Gui`] will automatically be reflected in the global settings [`Map`] and
+//! vice versa.
+//!
+//! # Defining a GUI
+//!
+//! ```ignore
+//! #[derive(Gui)]
+//! struct Settings {
+//!     /// General Settings
+//!     _general_settings: Title,
+//!     /// Use Game Time
+//!     ///
+//!     /// This is the tooltip.
+//!     use_game_time: bool,
+//! }
+//! ```
+//!
+//! The type can then be used like so:
+//!
+//! ```ignore
+//! let mut settings = Settings::register();
+//!
+//! loop {
+//!    settings.update();
+//!    // Do something with the settings.
+//! }
+//! ```
+//!
+//! Check the [`Gui`](macro@Gui) derive macro and the [`Gui`](trait@Gui) trait
+//! for more information.
+//!
+//! # Modifying the global settings map
+//!
+//! ```no_run
+//! # use asr::settings;
+//! let mut map = settings::Map::load();
+//! map.insert("key", &true.into());
+//! map.store();
+//! ```
+//!
+//! Check the [`Map`](struct@Map) struct for more information.
 
 pub mod gui;
 mod map;