Merge pull request #2982 from Assumeru/explain

Comments to explain the arcane workings of Morrowind

apps/openmw/mwmechanics/spelllist.hpp

@@ -26,6 +26,14 @@ namespace MWMechanics
 
     class Spells;
 
+    /// Multiple instances of the same actor share the same spell list in Morrowind.
+    /// The most obvious result of this is that adding a spell or ability to one instance adds it to all instances.
+    /// @note The original game will only update visual effects associated with any added abilities for the originally targeted actor,
+    ///       changing cells applies the update to all actors.
+    /// Aside from sharing the same active spell list, changes made to this list are also written to the actor's base record.
+    /// Interestingly, it is not just scripted changes that are persisted to the base record. Curing one instance's disease will cure all instances.
+    /// @note The original game is inconsistent in persisting this example;
+    ///       saving and loading the game might reapply the cured disease depending on which instance was cured.
     class SpellList
     {
             const std::string mId;

apps/openmw/mwworld/esmstore.hpp

@@ -264,8 +264,11 @@ namespace MWWorld
         // To be called when we are done with dynamic record loading
         void checkPlayer();
 
+        /// @return The number of instances defined in the base files. Excludes changes from the save file.
         int getRefCount(const std::string& id) const;
 
+        /// Actors with the same ID share spells, abilities, etc.
+        /// @return The shared spell list to use for this actor and whether or not it has already been initialized.
         std::pair<std::shared_ptr<MWMechanics::SpellList>, bool> getSpellList(const std::string& id) const;
     };