Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doxygen comments to character.h #42579

Merged
merged 4 commits into from
Jul 31, 2020
Merged

doxygen comments to character.h #42579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f7e4a9b
Update character.h
Jerimee Jul 30, 2020
5df99c0
Update character.h
Jerimee Jul 30, 2020
817470d
very m to iexamine.cpp
Jerimee Jul 31, 2020
a3e4632
vision modes do not necessarily match json ids or flags
Jerimee Jul 31, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 61 additions & 43 deletions src/character.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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
};

Expand All @@ -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
};

Expand Down Expand Up @@ -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,
Expand All @@ -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 {
Expand All @@ -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;
Expand Down Expand Up @@ -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.
Expand All @@ -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 );
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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 = "" );
Expand Down Expand Up @@ -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;
/**
Expand Down Expand Up @@ -2477,8 +2495,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;

/**
Expand Down Expand Up @@ -2535,13 +2553,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;

Expand Down Expand Up @@ -2586,13 +2604,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
12 changes: 6 additions & 6 deletions src/iexamine.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -334,9 +334,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();
Expand All @@ -348,12 +348,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 );
Expand All @@ -375,7 +375,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 );
Expand Down