Changed signatures & docs for clarity

src/activity_handlers.cpp

@@ -2731,7 +2731,7 @@ void activity_handlers::aim_do_turn( player_activity *act, player * )
     if( act->index == 0 ) {
         g->m.invalidate_map_cache( g->get_levz() );
         g->m.build_map_cache( g->get_levz() );
-        avatar_action::fire( g->u, g->m );
+        avatar_action::aim_do_turn( g->u, g->m );
     }
 }
 

src/avatar_action.cpp

@@ -701,20 +701,20 @@ bool avatar_action::fire_check( avatar &you, const map &m, const targeting_data
     return false;
 }
 
-bool avatar_action::fire( avatar &you, map &m )
+void avatar_action::aim_do_turn( avatar &you, map &m )
 {
     targeting_data args = you.get_targeting_data();
     if( !args.relevant ) {
         // args missing a valid weapon, this shouldn't happen.
         debugmsg( "Player tried to fire a null weapon." );
-        return false;
+        return;
     }
     // If we were wielding this weapon when we started aiming, make sure we still are.
     bool lost_weapon = ( args.held && &you.weapon != args.relevant );
     bool failed_check = !avatar_action::fire_check( you, m, args );
     if( lost_weapon || failed_check ) {
         you.cancel_activity();
-        return false;
+        return;
     }
 
     int reload_time = 0;
@@ -746,12 +746,12 @@ bool avatar_action::fire( avatar &you, map &m )
                                       args.relevant, you.ammo_location ) : you.select_ammo( *gun );
             if( !opt ) {
                 // Menu canceled
-                return false;
+                return;
             }
             reload_time += opt.moves();
             if( !gun->reload( you, std::move( opt.ammo ), 1 ) ) {
                 // Reload not allowed
-                return false;
+                return;
             }
 
             // Burn 0.2% max base stamina x the strength required to fire.
@@ -787,7 +787,7 @@ bool avatar_action::fire( avatar &you, map &m )
             you.moves = previous_moves;
         }
         g->reenter_fullscreen();
-        return false;
+        return;
     }
     // Recenter our view
     g->draw_ter();
@@ -828,29 +828,28 @@ bool avatar_action::fire( avatar &you, map &m )
         you.mod_power_level( units::from_kilojoule( -args.power_cost ) * shots );
     }
     g->reenter_fullscreen();
-    return shots != 0;
 }
 
-bool avatar_action::fire( avatar &you, map &m, item &weapon, int bp_cost )
+void avatar_action::fire_weapon( avatar &you, map &m, item &weapon, int bp_cost )
 {
     // TODO: bionic power cost of firing should be derived from a value of the relevant weapon.
     gun_mode gun = weapon.gun_current_mode();
     // gun can be null if the item is an unattached gunmod
     if( !gun ) {
         add_msg( m_info, _( "The %s can't be fired in its current state." ), weapon.tname() );
-        return false;
+        return;
     } else if( weapon.ammo_data() && !weapon.ammo_types().count( weapon.ammo_data()->ammo->type ) ) {
         add_msg( m_info, _( "The %s can't be fired while loaded with incompatible ammunition %s" ),
                  weapon.tname(), weapon.ammo_current() );
-        return false;
+        return;
     }
 
     targeting_data args = {
         TARGET_MODE_FIRE, &weapon, gun.target->gun_range( &you ),
         bp_cost, you.is_wielding( weapon ), gun->ammo_data()
     };
     you.set_targeting_data( args );
-    return avatar_action::fire( you, m );
+    avatar_action::aim_do_turn( you, m );
 }
 
 void avatar_action::mend( avatar &you, item_location loc )

src/avatar_action.h

@@ -46,26 +46,25 @@ void autoattack( avatar &you, map &m );
 void mend( avatar &you, item_location loc );
 
 /**
- * Returns true if the player is allowed to fire a given item, or false if otherwise.
- * reload_time is stored as a side effect of condition testing.
+ * Checks if the weapon is valid and if the player meets certain conditions for firing it.
  * @param args Contains item data and targeting mode for the gun we want to fire.
  * @return True if all conditions are true, otherwise false.
  */
 bool fire_check( avatar &you, const map &m, const targeting_data &args );
 
 /**
- * Handles interactive parts of gun firing (target selection, etc.).
- * @return Whether an attack was actually performed.
+ * Validates avatar's targeting_data, then handles interactive parts of gun firing
+ * (target selection, aiming, etc.)
  */
-bool fire( avatar &you, map &m );
+void aim_do_turn( avatar &you, map &m );
+
 /**
- * Handles interactive parts of gun firing (target selection, etc.).
- * This version stores targeting parameters for weapon, used for calls to the nullary form.
+ * Validates weapon, stores it into targeting_data and starts interactive aiming.
  * @param weapon Reference to a weapon we want to start aiming.
  * @param bp_cost The amount by which the player's power reserve is decreased after firing.
- * @return Whether an attack was actually performed.
  */
-bool fire( avatar &you, map &m, item &weapon, int bp_cost = 0 );
+void fire_weapon( avatar &you, map &m, item &weapon, int bp_cost = 0 );
+
 // Throw an item  't'
 void plthrow( avatar &you, item_location loc,
               const cata::optional<tripoint> &blind_throw_from_pos = cata::nullopt );

src/bionics.cpp

@@ -275,7 +275,7 @@ bool Character::activate_bionic( int b, bool eff_only )
         refund_power(); // Power usage calculated later, in avatar_action::fire
         bio_gun = item( bio.info().fake_item );
         g->refresh_all();
-        avatar_action::fire( g->u, g->m, bio_gun, units::to_kilojoule( bio.info().power_activate ) );
+        avatar_action::fire_weapon( g->u, g->m, bio_gun, units::to_kilojoule( bio.info().power_activate ) );
     } else if( bio.info().weapon_bionic ) {
         if( weapon.has_flag( flag_NO_UNWIELD ) ) {
             add_msg_if_player( m_info, _( "Deactivate your %s first!" ), weapon.tname() );
@@ -298,7 +298,7 @@ bool Character::activate_bionic( int b, bool eff_only )
         weapon.invlet = '#';
         if( bio.ammo_count > 0 ) {
             weapon.ammo_set( bio.ammo_loaded, bio.ammo_count );
-            avatar_action::fire( g->u, g->m, weapon );
+            avatar_action::fire_weapon( g->u, g->m, weapon );
             g->refresh_all();
         }
     } else if( bio.id == bio_ears && has_active_bionic( bio_earplugs ) ) {

src/game.cpp

@@ -7063,7 +7063,7 @@ void game::list_items_monsters()
     }
 
     if( ret == game::vmenu_ret::FIRE ) {
-        avatar_action::fire( u, m, u.weapon );
+        avatar_action::fire_weapon( u, m, u.weapon );
     }
     reenter_fullscreen();
 }

src/handle_action.cpp

@@ -1235,7 +1235,7 @@ static void fire()
                         turret.range(), 0, false, turret.ammo_data()
                     };
                     u.set_targeting_data( args );
-                    avatar_action::fire( g->u, g->m );
+                    avatar_action::aim_do_turn( g->u, g->m );
 
                     break;
                 }
@@ -1283,7 +1283,7 @@ static void fire()
     }
 
     if( u.weapon.is_gun() && !u.weapon.gun_current_mode().melee() ) {
-        avatar_action::fire( g->u, g->m, u.weapon );
+        avatar_action::fire_weapon( g->u, g->m, u.weapon );
     } else if( u.weapon.has_flag( flag_REACH_ATTACK ) ) {
         int range = u.weapon.has_flag( flag_REACH3 ) ? 3 : 2;
         if( u.has_effect( effect_relax_gas ) ) {
@@ -1982,7 +1982,7 @@ bool game::handle_action()
             case ACTION_FIRE_BURST: {
                 gun_mode_id original_mode = u.weapon.gun_get_mode_id();
                 if( u.weapon.gun_set_mode( gun_mode_id( "AUTO" ) ) ) {
-                    avatar_action::fire( u, m, u.weapon );
+                    avatar_action::fire_weapon( u, m, u.weapon );
                     u.weapon.gun_set_mode( original_mode );
                 }
                 break;

src/mutation.cpp

@@ -561,7 +561,7 @@ void Character::activate_mutation( const trait_id &mut )
         mut_ranged = item( mdata.ranged_mutation );
         add_msg_if_player( mdata.ranged_mutation_message() );
         g->refresh_all();
-        avatar_action::fire( g->u, g->m, mut_ranged );
+        avatar_action::fire_weapon( g->u, g->m, mut_ranged );
         tdata.powered = false;
         return;
     }