diff --git a/src/character.h b/src/character.h index 0f7959db8a39a..eabc4e9f73238 100644 --- a/src/character.h +++ b/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; #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( 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 { 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_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 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 /** 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 * 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 bool can_install_cbm_on_bp( const std::vector &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 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 /** 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 std::bitset 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 + /// turn the character expired, if calendar::before_time_starts it has not been set yet. + /// @todo change into an optional time_point time_died = calendar::before_time_starts; /** @@ -2534,13 +2552,13 @@ class Character : public Creature, public visitable // 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 &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 { 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 diff --git a/src/iexamine.cpp b/src/iexamine.cpp index 7afaaaf088104..58db68447e4a4 100644 --- a/src/iexamine.cpp +++ b/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 );