Add documentation to Team API

[patriciaahuang]

Added documentation to teamAPI.ts. The @throws were not included due to the error messages being self-explanatory.

[dti-github-bot]

[diff-counting] Significant lines: 32.

[andrew032011]

Tracing this down, it seems like additionally, it removes all references between the member, leaders, and formerMembers from this team. I.e. member, leader, formerMember will no longer have his team under subteams field and formerSubteams field.

Maybe add that in the docstring?

[andrew032011]

This can be in a separate PR, but I think this function should be renamed to clearTeam, since the team document doesn't actually get deleted from the DB. Assuming that is intentional, all we're doing here is removing all members, leaders, and formerMembers from the team.

[henry-li-06]

FYI the Team data type in IDOL is aggregated data from the members collection. Unlike a lot of the data types for the IDOL BE, an instance of a Team object isn't correlated to some doc in the teams collection for example.

In a sense it's a "view" on the members collection.

So Team is

export type Team = {
  uuid: string;
  name: string;
  leaders: IdolMember[];
  members: IdolMember[];
  formerMembers: IdolMember[];
};

A team exists if there are 1+ members in the members collection where the team's name is in a member's subteams or formerSubteamsfields. The team object is created by grouping members by their teams in a many to many relationship kinda situation (a member can have multiple teams and a team has multiple members).

The team's former members are just the members where the team name is listed under the formerSubteams field for the member. The team's leaders are members whose roles are either pm or tpm and have the team name listed under the members field. The team's members are the same as before just without pm or tpm role.

Any operations on teams in the BE are basically just operations on members docs to reflect/persist these team changes.

And teams really aren't used at all within IDOL (could be an interesting idea to explore, maybe for coffee chats or whatever). The main reason the teams collection was removed in favor of this implementation where teams are just a view on the members collection is related to usage of IDOL for member profiles. The members collection was the source of truth for member profile information for the website (updated through the pull-from-idol job). Teams used to be separate from members which led to 2 representations of essentially the same data (who is on what team). That led to some problems like data being out of sync and then just managing the same data in 2 places is just extra work.

The original PR if you want more info: #199