doxygen comments to character.h (#42579)

src/character.h

@@ -66,6 +66,7 @@ class vehicle;
 struct bionic;
 struct construction;
 struct dealt_projectile_attack;
+/// @brief Item slot used to apply modifications from food and meds
 struct islot_comestible;
 struct itype;
 class recipe_subset;
@@ -83,6 +84,8 @@ using drop_locations = std::list<drop_location>;
 
 #define MAX_CLAIRVOYANCE 40
 
+/// @brief type of conditions that effect vision
+/// @note vision modes do not necessarily match json ids or flags
 enum vision_modes {
     DEBUG_NIGHTVISION,
     NV_GOGGLES,
@@ -92,8 +95,11 @@ enum vision_modes {
     FULL_ELFA_VISION,
     ELFA_VISION,
     CEPH_VISION,
+    /// mutate w/ id "FEL_NV" & name "Feline Vision" see pretty well at night
     FELINE_VISION,
+    /// Bird mutation named "Avian Eyes": Perception +4
     BIRD_EYE,
+    /// mutate w/ id "URSINE_EYE" & name "Ursine Vision" see better in dark, nearsight in light
     URSINE_VISION,
     BOOMERED,
     DARKNESS,
@@ -176,13 +182,25 @@ constexpr inline int operator-( const T &lhs, const fatigue_levels &rhs )
     return lhs - static_cast<T>( rhs );
 }
 
-// Sleep deprivation is defined in minutes, and although most calculations scale linearly,
-// maluses are bestowed only upon reaching the tiers defined below.
+/** @brief five levels of consequences for days without sleep
+    @details Sleep deprivation, distinct from fatigue, is defined in minutes. Although most
+    calculations scale linearly, malus is bestowed only upon reaching the tiers defined below.
+    @note Sleep deprivation increases fatigue. Fatigue increase scales with the severity of sleep
+    deprivation.
+    @note Sleep deprivation kicks in if lack of sleep is avoided with stimulants or otherwise for
+    long periods of time
+    @see https://github.com/CleverRaven/Cataclysm-DDA/blob/master/src/character.cpp#L5566
+*/
 enum sleep_deprivation_levels {
+    /// 2 days
     SLEEP_DEPRIVATION_HARMLESS = 2 * 24 * 60,
+    /// 4 days
     SLEEP_DEPRIVATION_MINOR = 4 * 24 * 60,
+    /// 7 days
     SLEEP_DEPRIVATION_SERIOUS = 7 * 24 * 60,
+    /// 10 days
     SLEEP_DEPRIVATION_MAJOR = 10 * 24 * 60,
+    /// 14 days
     SLEEP_DEPRIVATION_MASSIVE = 14 * 24 * 60
 };
 
@@ -199,30 +217,31 @@ struct enum_traits<blood_type> {
     static constexpr auto last = blood_type::num_bt;
 };
 
-// This tries to represent both rating and
-// character's decision to respect said rating
+/// @brief how digestible or palatable an item is
+/// @details This tries to represent both rating and character's decision to respect said rating
+/// (ie "they can eat it, though they are disgusted by it")
 enum edible_rating {
-    // Edible or we pretend it is
+    /// Edible or we pretend it is
     EDIBLE,
-    // Not food at all
+    /// Not food at all
     INEDIBLE,
-    // Not food because mutated mouth/system
+    /// Not food because character has mutated mouth/system
     INEDIBLE_MUTATION,
-    // You can eat it, but it will hurt morale
+    /// You can eat it, but it will hurt morale because of negative trait such as Hates Fruit
     ALLERGY,
-    // Smaller allergy penalty
+    /// Smaller allergy penalty
     ALLERGY_WEAK,
-    // Cannibalism (unless psycho/cannibal)
+    /// Penalty for eating human flesh (unless psycho/cannibal)
     CANNIBALISM,
-    // This has parasites
+    /// Comestible has parasites
     PARASITES,
-    // Rotten or not rotten enough (for saprophages)
+    /// Rotten (or, for saprophages, not rotten enough)
     ROTTEN,
-    // Can provoke vomiting if you already feel nauseous.
+    /// Can provoke vomiting if you already feel nauseous.
     NAUSEA,
-    // We can eat this, but we'll overeat
+    /// We can eat this, but we'll suffer from overeat
     TOO_FULL,
-    // Some weird stuff that requires a tool we don't have
+    /// Some weird stuff that requires a tool we don't have
     NO_TOOL
 };
 
@@ -279,6 +298,8 @@ inline social_modifiers operator+( social_modifiers lhs, const social_modifiers
     return lhs;
 }
 
+/// @brief Four ability stats available on character creation
+/// @details  Default is 8. Minimum value is 4 and 14 is considered to be max human value.
 enum class character_stat : char {
     STRENGTH,
     DEXTERITY,
@@ -302,17 +323,17 @@ class Character : public Creature, public visitable<Character>
         }
 
         character_id getID() const;
-        // sets the ID, will *only* succeed when the current id is not valid
-        // allows forcing a -1 id which is required for templates to not throw errors
+        /// sets the ID, will *only* succeed when the current id is not valid
+        /// allows forcing a -1 id which is required for templates to not throw errors
         void setID( character_id i, bool force = false );
 
         field_type_id bloodType() const override;
         field_type_id gibType() const override;
         bool is_warm() const override;
         bool in_species( const species_id &spec ) const override;
-        // Turned to false for simulating NPCs on distant missions so they don't drop all their gear in sight
+        /// Turned to false for simulating NPCs on distant missions so they don't drop all their gear in sight
         bool death_drops;
-        // Is currently in control of a vehicle
+        /// Is currently in control of a vehicle
         bool controlling_vehicle = false;
 
         enum class comfort_level : int {
@@ -324,8 +345,8 @@ class Character : public Creature, public visitable<Character>
             very_comfortable = 10
         };
 
-        // Character stats
-        // TODO: Make those protected
+        /// @brief Character stats
+        /// @todo Make those protected
         int str_max;
         int dex_max;
         int int_max;
@@ -488,9 +509,9 @@ class Character : public Creature, public visitable<Character>
         /** Returns the player's speed for swimming across water tiles */
         int  swim_speed() const;
         /**
-         * Adds a reason for why the player would miss a melee attack.
+         * @brief Adds a reason for why the player would miss a melee attack.
          *
-         * To possibly be messaged to the player when he misses a melee attack.
+         * @details To possibly be messaged to the player when he misses a melee attack.
          * @param reason A message for the player that gives a reason for him missing.
          * @param weight The weight used when choosing what reason to pick when the
          * player misses.
@@ -507,8 +528,8 @@ class Character : public Creature, public visitable<Character>
           * Handles passive regeneration of pain and maybe hp.
           */
         void regen( int rate_multiplier );
-        // called once per 24 hours to enforce the minimum of 1 hp healed per day
-        // TODO: Move to Character once heal() is moved
+        /// called once per 24 hours to enforce the minimum of 1 hp healed per day
+        /// @todo Move to Character once heal() is moved
         void enforce_minimum_healing();
         /** get best quality item that this character has */
         item *best_quality_item( const quality_id &qual );
@@ -1054,10 +1075,8 @@ class Character : public Creature, public visitable<Character>
 
         bool can_install_cbm_on_bp( const std::vector<bodypart_id> &bps ) const;
 
-        /**
-         * Returns resistances on a body part provided by mutations
-         */
-        // TODO: Cache this, it's kinda expensive to compute
+        /// @brief Returns resistances on a body part provided by mutations
+        /// @todo Cache this, it's kinda expensive to compute
         resistances mutation_armor( bodypart_id bp ) const;
         float mutation_armor( bodypart_id bp, damage_type dt ) const;
         float mutation_armor( bodypart_id bp, const damage_unit &du ) const;
@@ -1786,10 +1805,9 @@ class Character : public Creature, public visitable<Character>
         void use_fire( int quantity );
         void assign_stashed_activity();
         bool check_outbounds_activity( const player_activity &act, bool check_only = false );
-        /** Legacy activity assignment, does not work for any activites using
-         * the new activity_actor class and may cause issues with resuming.
-         * TODO: delete this once migration of activites to the activity_actor system is complete
-         */
+        /// @warning Legacy activity assignment, does not work for any activites using
+        /// the new activity_actor class and may cause issues with resuming.
+        /// @todo delete this once migration of activites to the activity_actor system is complete
         void assign_activity( const activity_id &type, int moves = calendar::INDEFINITELY_LONG,
                               int index = -1, int pos = INT_MIN,
                               const std::string &name = "" );
@@ -2030,13 +2048,13 @@ class Character : public Creature, public visitable<Character>
         /** Set vitamin deficiency/excess disease states dependent upon current vitamin levels */
         void update_vitamins( const vitamin_id &vit );
         /**
-         * Check current level of a vitamin
+         * @brief Check current level of a vitamin
          *
-         * Accesses level of a given vitamin.  If the vitamin_id specified does not
+         * @details Accesses level of a given vitamin.  If the vitamin_id specified does not
          * exist then this function simply returns 0.
          *
-         * @param vit ID of vitamin to check level for.
-         * @returns current level for specified vitamin
+         * @param vit ID of vitamin to check level for (ie "vitA", "vitB").
+         * @returns character's current level for specified vitamin
          */
         int vitamin_get( const vitamin_id &vit ) const;
         /**
@@ -2476,8 +2494,8 @@ class Character : public Creature, public visitable<Character>
         std::bitset<NUM_VISION_MODES> vision_mode_cache;
         int sight_max = 0;
 
-        // turn the character expired, if calendar::before_time_starts it has not been set yet.
-        // TODO: change into an optional<time_point>
+        /// turn the character expired, if calendar::before_time_starts it has not been set yet.
+        /// @todo change into an optional<time_point>
         time_point time_died = calendar::before_time_starts;
 
         /**
@@ -2534,13 +2552,13 @@ class Character : public Creature, public visitable<Character>
         // is recalculated every turn in Character::recalculate_enchantment_cache
         enchantment enchantment_cache;
         player_activity destination_activity;
-        // A unique ID number, assigned by the game class. Values should never be reused.
+        /// A unique ID number, assigned by the game class. Values should never be reused.
         character_id id;
 
         units::energy power_level;
         units::energy max_power_level;
 
-        /** Needs (hunger, starvation, thirst, fatigue, etc.) */
+        /// @brief Needs (hunger, starvation, thirst, fatigue, etc.)
         int stored_calories;
         int healthy_calories;
 
@@ -2585,13 +2603,13 @@ class Character : public Creature, public visitable<Character>
 
 Character &get_player_character();
 
-// Little size helper, exposed for use in deserialization code.
+/// Little size helper, exposed for use in deserialization code.
 creature_size calculate_size( const Character &c );
 
 template<>
 struct enum_traits<character_stat> {
     static constexpr character_stat last = character_stat::DUMMY_STAT;
 };
-/**Get translated name of a stat*/
+/// Get translated name of a stat
 std::string get_stat_name( character_stat Stat );
 #endif // CATA_SRC_CHARACTER_H

src/iexamine.cpp

@@ -332,9 +332,9 @@ void iexamine::nanofab( player &p, const tripoint &examp )
 
 }
 
-/**
- * Use "gas pump."  Will pump any liquids on tile.
- */
+
+/// @brief Use "gas pump."
+/// @details Will pump any liquids on tile.
 void iexamine::gaspump( player &p, const tripoint &examp )
 {
     map &here = get_map();
@@ -346,12 +346,12 @@ void iexamine::gaspump( player &p, const tripoint &examp )
     map_stack items = here.i_at( examp );
     for( auto item_it = items.begin(); item_it != items.end(); ++item_it ) {
         if( item_it->made_of( phase_id::LIQUID ) ) {
-            ///\EFFECT_DEX decreases chance of spilling gas from a pump
+            /// @note \EFFECT_DEX decreases chance of spilling gas from a pump
             if( one_in( 10 + p.get_dex() ) ) {
                 add_msg( m_bad, _( "You accidentally spill the %s." ), item_it->type_name() );
                 static const auto max_spill_volume = units::from_liter( 1 );
                 const int max_spill_charges = std::max( 1, item_it->charges_per_volume( max_spill_volume ) );
-                ///\EFFECT_DEX decreases amount of gas spilled from a pump
+                /// @note \EFFECT_DEX decreases amount of gas spilled, if gas is spilled from pump
                 const int qty = rng( 1, max_spill_charges * 8.0 / std::max( 1, p.get_dex() ) );
 
                 item spill = item_it->split( qty );
@@ -373,7 +373,7 @@ void iexamine::gaspump( player &p, const tripoint &examp )
 
 void iexamine::translocator( player &, const tripoint &examp )
 {
-    // TODO: fix point types
+    /// @todo fix point types
     const tripoint_abs_omt omt_loc( ms_to_omt_copy( get_map().getabs( examp ) ) );
     avatar &player_character = get_avatar();
     const bool activated = player_character.translocators.knows_translocator( omt_loc );