Making comments more detailed and descriptive

[Anurag19101996]

Hello,
As we discussed that the code will be used for all type of users, could you make the comments more detailed and descriptive?

I have added one example below for :
https://github.com/uw-ssec/MAWpy/blob/main/src/mawpy/steps/incremental_clustering.py#L58-L73

Before:

def _merge_stays(stay_to_update: int, updated_stay: int, df_by_user: pd.DataFrame, group_avgs: pd.DataFrame,
                 group_avgs_index_to_update: int) -> pd.DataFrame:
    """
        Merges two stays for a user and updates the mean_lat and mean_long of the stay.
    """
    df_by_user.loc[df_by_user[STAY] == stay_to_update, STAY] = updated_stay
    merged_values = df_by_user[df_by_user[STAY] == updated_stay][STAY_LAT_LONG]
    new_avg = merged_values.apply(_mean_ignore_minus_ones).fillna(-1)

    group_avgs.loc[group_avgs[STAY] == updated_stay, STAY_LAT_LONG] = new_avg.values
    df_by_user.loc[df_by_user[STAY] == updated_stay, STAY_LAT_LONG] = new_avg.values

    group_avgs.loc[group_avgs_index_to_update, STAY] = updated_stay
    group_avgs.loc[group_avgs_index_to_update, STAY_LAT_LONG] = new_avg.values

    return df_by_user

After:

def _merge_stays(stay_to_update: int, updated_stay: int, df_by_user: pd.DataFrame, group_avgs: pd.DataFrame,
                 group_avgs_index_to_update: int) -> pd.DataFrame:
    """
        Merges two stays for a user and updates the mean_lat and mean_long of the stay. 
    """
# Update the 'STAY' column in 'df_by_user' DataFrame where the current value matches 'stay_to_update'
    df_by_user.loc[df_by_user[STAY] == stay_to_update, STAY] = updated_stay

# Filter 'df_by_user' DataFrame to get rows where 'STAY' equals 'updated_stay' and select 'STAY_LAT_LONG' column values
    merged_values = df_by_user[df_by_user[STAY] == updated_stay][STAY_LAT_LONG]

# Apply '_mean_ignore_minus_ones' function to 'merged_values', filling NaNs with -1
    new_avg = merged_values.apply(_mean_ignore_minus_ones).fillna(-1)

# Update 'STAY_LAT_LONG' column in 'group_avgs' DataFrame where 'STAY' equals 'updated_stay' with 'new_avg' values
    group_avgs.loc[group_avgs[STAY] == updated_stay, STAY_LAT_LONG] = new_avg.values

# Update 'STAY_LAT_LONG' column in 'df_by_user' DataFrame where 'STAY' equals 'updated_stay' with 'new_avg' values
    df_by_user.loc[df_by_user[STAY] == updated_stay, STAY_LAT_LONG] = new_avg.values

# Update 'STAY' column in 'group_avgs' DataFrame at specific 'group_avgs_index_to_update' with 'updated_stay'
    group_avgs.loc[group_avgs_index_to_update, STAY] = updated_stay

# Update 'STAY_LAT_LONG' column in 'group_avgs' DataFrame at specific 'group_avgs_index_to_update' with 'new_avg' values
    group_avgs.loc[group_avgs_index_to_update, STAY_LAT_LONG] = new_avg.values

    return df_by_user

Although not very very detailed as this, but could you make documentation for the code somewhat on similar lines?

@qzchen-uw @gracejia513 @anujsinha3 @carlosgjs