From 75f5ce065efb6a186570b365c88e564871915d76 Mon Sep 17 00:00:00 2001
From: Daniel Schadt <kingdread@gmx.de>
Date: Thu, 23 Jul 2020 17:57:59 +0200
Subject: more documentation & adjustments

---
 src/analyzers/mod.rs       | 17 +++++++++++++----
 src/analyzers/raids/mod.rs | 11 +++++++++++
 src/analyzers/raids/w7.rs  |  1 +
 src/lib.rs                 |  4 ++++
 4 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/src/analyzers/mod.rs b/src/analyzers/mod.rs
index 880e5df..d6315f3 100644
--- a/src/analyzers/mod.rs
+++ b/src/analyzers/mod.rs
@@ -1,16 +1,23 @@
 //! Traits and structures to analyze fights.
 //!
-//! Fights need different logic to determine some data, for example each fight has a different way
-//! to determine whether or not the Challenge Mote was activated, whether or not the fight was
-//! successful, ...
+//! Fights need different logic in order to determine specific data, for example each fight has a
+//! different way to determine whether or not the Challenge Mote was activated, whether or not the
+//! fight was successful, ...
 //!
-//! This module aims to unify that logic by providing a trait [`Analyzer`][Analyzer], which
+//! This module aims to unify that logic by providing the [`Analyzer`][Analyzer] trait, which
 //! provides a unified interface to query this information. You can use
 //! [`Log::analyzer`][Log::analyzer] or [`for_log`][for_log] to obtain an analyzer fitting for the
 //! encounter that is represented by the log.
 //!
+//! Most of the time, you will be dealing with a dynamically dispatched version of
+//! [`Analyzer`][Analyzer], that is either `&dyn Analyzer` or `Box<dyn Analyzer>`. Also keep in
+//! mind that an analyzer keeps a reference to the log that it is analyzing, which can be accessed
+//! through [`Analyzer::log`][Analyzer::log].
+//!
 //! The implementation of the different analyzers is split off in different submodules:
 //! * [`raids`][raids] for the raid-related encounters.
+//! * [`fractals`][fractals] for the fractal-specific encounters.
+//! * [`strikes`][strikes] for the strike-mission specific encounters.
 //!
 //! Note that you should not create concrete analyzers on your own, as the behaviour is not
 //! specified when you use a wrong analyzer for the given log. Rely only on
@@ -52,6 +59,8 @@ impl Outcome {
 }
 
 /// An [`Analyzer`][Analyzer] is something that implements fight-dependent analyzing of the log.
+///
+/// For more information and explanations, see the [module level documentation][self].
 pub trait Analyzer {
     /// Returns a reference to the log being analyzed.
     fn log(&self) -> &Log;
diff --git a/src/analyzers/raids/mod.rs b/src/analyzers/raids/mod.rs
index 33d54ce..39fb823 100644
--- a/src/analyzers/raids/mod.rs
+++ b/src/analyzers/raids/mod.rs
@@ -1,3 +1,9 @@
+//! Analyzers for raid logs.
+//!
+//! Most of the fights can use the [`GenericRaid`][GenericRaid] analyzer. The exception to this are
+//! fights which have a Challenge Mote (Wing 4, Wing 5, Wing 6, Wing 7), and fights which need to
+//! use a different method to determine their outcome (Xera, Deimos, Soulless Horror, Conjured
+//! Amalgamate, Qadim).
 use crate::{
     analyzers::{helpers, Analyzer, Outcome},
     Log,
@@ -19,6 +25,11 @@ mod w7;
 pub use w7::{CardinalAdina, CardinalSabir, QadimThePeerless};
 
 /// A generic raid analyzer that works for bosses without special interactions.
+///
+/// This analyzer always returns `false` for the Challenge Mote calculation.
+///
+/// The outcome of the fight is determined by whether the boss agent has a death event - which
+/// works for a lot of fights, but not all of them.
 #[derive(Debug, Clone, Copy)]
 pub struct GenericRaid<'log> {
     log: &'log Log,
diff --git a/src/analyzers/raids/w7.rs b/src/analyzers/raids/w7.rs
index 54073a3..480c303 100644
--- a/src/analyzers/raids/w7.rs
+++ b/src/analyzers/raids/w7.rs
@@ -70,6 +70,7 @@ impl<'log> Analyzer for CardinalSabir<'log> {
 
 pub const QADIMP_CM_HEALTH: u64 = 51_000_000;
 
+/// Analyzer for the final fight of Wing 7, Qadim The Peerless.
 #[derive(Debug, Clone, Copy)]
 pub struct QadimThePeerless<'log> {
     log: &'log Log,
diff --git a/src/lib.rs b/src/lib.rs
index a343cfe..bd2acca 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -884,6 +884,10 @@ impl Log {
     ///
     /// This can be used as an indication whether the fight was successful (`true`) or not
     /// (`false`).
+    ///
+    /// If you want to properly determine whether a fight was successful, check the
+    /// [`Analyzer::outcome`][Analyzer::outcome] method, which does more sophisticated checks
+    /// (dependent on the boss).
     pub fn was_rewarded(&self) -> bool {
         self.events().iter().any(|e| {
             if let EventKind::Reward { .. } = e.kind() {
-- 
cgit v1.2.3