more documentation

1 files changed, 28 insertions, 0 deletions

diff --git a/src/minemod.rs b/src/minemod.rs
index f45b897..456d1c6 100644
--- a/src/minemod.rs
+++ b/src/minemod.rs
@@ -1,3 +1,27 @@
+//! Module to interact with installed mods and modpacks.
+//!
+//! Due to technical reasons (`mod` being a Rust keyword), this module is called `minemod` and the
+//! mod objects are called [`MineMod`].
+//!
+//! Simple mods are represented by [`MineMod`], which can be opened by [`MineMod::open`]. Valid
+//! mods are identified by their `mod.conf`, which contains metadata about the mod.
+//!
+//! Modpacks can be represented by [`Modpack`] and loaded through [`Modpack::open`]. A modpack is
+//! just a collection of mods grouped together, and the modpack directory needs to have a
+//! `modpack.conf` in its directory.
+//!
+//! # Mods and Packs United
+//!
+//! In some cases, we cannot know in advance whether we are dealing with a mod or a modpack (e.g.
+//! when downloading content from ContentDB). Therefore, the trait [`ModContainer`] exists, which
+//! can be used as a trait object (`Box<dyn ModContainer>`). It provides the most important methods
+//! and allows downcasting through `Any`.
+//!
+//! If you want to work with the mods directly, you can use [`ModContainer::mods`], which returns
+//! the mod itself for [`MineMod`]s, and all contained mods for [`Modpack`]s.
+//!
+//! If you want to open a directory as a [`ModContainer`], you can use [`open_mod_or_pack`].
+
 use std::{
     any::Any,
     collections::HashMap,
@@ -20,6 +44,7 @@ pub struct MineMod {
 }
 
 impl MineMod {
+    /// Opens the given directory as a mod.
     pub fn open<P: AsRef<Path>>(path: P) -> Result<MineMod> {
         MineMod::open_path(path.as_ref())
     }
@@ -93,6 +118,7 @@ pub struct Modpack {
 }
 
 impl Modpack {
+    /// Opens the given directory as a modpack.
     pub fn open<P: AsRef<Path>>(path: P) -> Result<Modpack> {
         Modpack::open_path(path.as_ref())
     }
@@ -154,6 +180,8 @@ impl fmt::Display for Modpack {
 }
 
 /// A thing that can contain mods.
+///
+/// This is useful for code that should deal with both mods and modpacks.
 pub trait ModContainer: Any + fmt::Display {
     /// Returns the name of the mod container.
     fn name(&self) -> Result<String>;