Updated comments

.gitignore

@@ -453,3 +453,6 @@ $RECYCLE.BIN/
 
 .env.local
 .vercel
+
+# for ella 
+airtable.ts

lib/people.ts

@@ -2,11 +2,22 @@ import { Attachment } from "airtable";
 import { base, getImgUrlFromAttachmentObj } from "./airtable";
 /**
  * @typedef Person
- * all possible information about a person
- * this is displayed on the "People" page on the website 
+ * all possible information about a person, including their name, title (professor, undergrad,grad, stella, etc), and their bio/profile photo
+ * this is displayed on the "People" page on the website
+ * @property {string} id: id of the person, held by airtable- 
+ * to find this value, click on an airtable field/person, and look at the URL at the part with the value ./recxxxxxx
+ * the value of their id is that recxxxx value from the URL
+ * @property {string} name: Person's displayed name on this section
+ * @property {string} title:  Displayed on the website, but describes their role such as "Professor","undergraduate researcher", etc.
+ * This doesn't work to actually organize the people, which is why we also have the "Role" field
+ * @property {string} role: Drop-down version of title, used to sort people on the website (professor -> phd -> grad/ug etc)
+ * @property {string} status: Drop down on airtable indicating if a person is active or inactive- this is used to also sort graduate and undergraduate students
+ * @property {string} bio : Bio of a particular person, displayed on the "people" page of the website
+ * @property {string} profile_photo: URL to someone's profile photo, from the airtable database
+ * 
  */
 export type Person = {
-  id: string;
+  id: string; 
   name: string;
   title: string;
   role: string;
@@ -17,7 +28,15 @@ export type Person = {
 /**
  * @typedef PartialPerson
  * concated set of information about a person
- * this is displayed on the "Projects" areas of the website
+ * used in the files - "Teammembers.tsx" and "Project.ts" and "Sig.ts"
+ * We have this type because it allows us to more quickly fetch content about people in cases where we don't need their bios
+ * this is displayed on the "Projects" and "Sigs" part of the website, which only display someone's name and if they're active/graduated
+ * @property {string} id: id of the person, held by airtable- look at @typedef Person for more info on how to find this
+ * @property {string} name: Person's displayed name on this section
+ * @property {string} title:  Not displayed here, but describes their role such as "Professor","undergraduate researcher", etc.
+ * @property {string} role: Drop-down version of title, used to sort people on the list of names (professor -> phd -> grad/ug etc), on the SIG and project pages
+ * @property {string} bio : Bio of a particular person, not displayed on the "projects" or "sig" part of the website
+ * @property {string} profile_photo: URL to someone's profile photo, from the airtable database- not displayed in these sections
  */
 export type PartialPerson = {
   id: string;
@@ -29,7 +48,11 @@ export type PartialPerson = {
 /**
  * @function fetchPeople
  * @returns array of People type
- * fetches all information from the Airtable DB about a specific person
+ * at a high level, fetches all information from the Airtable DB about all people in the database
+ * steps:
+ *  1. Select the base from airtable (in this case, "people")
+ *  2. For each page (person), we push the people onto the "Results" array, and then callback for the next page
+ *  3. Continue step 2 until this process is completed and all people are pushed onto the results array
  */
 export async function fetchPeople(): Promise<Person[]> {
   return new Promise((resolve, reject) => {
@@ -73,13 +96,14 @@ export async function fetchPeople(): Promise<Person[]> {
   });
 };
 /**
- * @function sortPeople - sorts an array of people into professors, students, active, non active, and stella !
- * @param people Person[]
- * @returns array of Person[]
+ * @function sortPeople - sorted array of people where people are in categories: professors, phds, students (grad and ugrad), active, non active, and stella !
+ * We use this in the people, project, and sig pages of the website, where we sort students and professors
+ * @param people Person[] 
+ * @returns array of Person[]in the correct order 
  */
 
 export function sortPeople(people: Person[]): Person[] {
-  // split active and alumni
+  // split active and alumni via the "status" parameter of the Person type
   let activePeople: Person[] = people.filter((person) => {
     return person.status === "Active";
   });

lib/project.ts

@@ -30,7 +30,15 @@ export type Project = {
 };
 /**
  * @typedef {object} PartialProject
+ * We use this in the "Sig" page, which describes a SIG and its associated projects
+ * We also have this because fetching all information about a project is more costly, and people are directly associated w/ SIGs as part of airtable
+ * and because publications, videos, and multiple images are not displayed on the SIG page
+ * @property {string} id: id of the project w/in Airtable projects database
+ * @property {string} name: working name of the project, stored w/in database
+ * @property {string} banner_image: Image URL of banner_image, stored as a string 
+ * @property {string} status string stating if the project is active or a past project 
  * intended to give a subset of information about a project, including id, name, banner image, description, and status
+ * 
  */
 
 export type PartialProject = {
@@ -41,9 +49,13 @@ export type PartialProject = {
   status: string;
 };
 /**
- * 
+ * @function getProject 
+ * We have this to get projects to display on each of the SIG pages
+ * It has the default value of "getAllData"
  * @param projectId 
- * @param getAllData 
+ * @param getAllData - default value of "False" so that this function defaults to just providing PartialProject info
+ * If getAllData is true, then it also recieves the partial images and publications
+ * getAllData is true in [id].txt and false in sig.ts
  * @returns partial project info, images, and related publications from nested functions
  * This is what is actually used to display project information
  */
@@ -56,9 +68,10 @@ export async function getProject(
     const people = await fetchPeople();
     // fetch people returns an array of people 
     // this will then be used to add information about project members to each project 
-
+    // We fetch people because people are directly mapped to their SIGS in the Airtable
+    // return record is the information related to the project w/ "projectid"
     base("Projects").find(projectId, async function (err, record) {
-      // return record is the information related to the project w/ "projectid"
+
       if (err) {
         reject(err);
         return;
@@ -78,12 +91,13 @@ export async function getProject(
           return fetchedMembers.includes(person.name);
         })
       );
+      // returns an array w/ type partial person (may not be an explicit type)
+      // mapped from the set of "people" filtered from the peopleOnProj function
       const partialPeopleOnProj: PartialPerson[] = peopleOnProj.map(
-        // returns an array w/ type partial person (may not be an explicit type)
-        // mapped from the set of "people" filtered from the peopleOnProj function
+      // this is a subset of the information of every person in the filtered people array
         (person) => {
           return {
-            // this is a subset of the information of every person in the filtered people array
+
             id: person.id,
             name: person.name,
             role: person.role,
@@ -141,10 +155,17 @@ type ProjectImages = {
   }[];
 };
 /**
- * 
+ * @function fetchProjectImages
  * @param imageDocId 
  * @returns an array of <ProjectImages> for a given project
- * Called within the getProject function
+ * Called within the getProject function, specifically in the "project.ts" page 
+ * steps for this function
+ *   1. Select the base from airtable (in this case, "Project Images")
+ *   2. Just find images for a specific project- denoted by "imageDocID"
+ *          Our "Project Images" DB is organized by project, so each project has its own unique ID
+ *   3. Each image is organized via "Image_i_description" and "Image_i", so we map i in range(1,5) to get each image
+ *   4. Lastly, if there is both an image URL and an image description, we push that onto the "explainerImages" array
+ *   5. We resolve the promise w/ that array of Explainer images
  */
 
 export async function fetchProjectImages(
@@ -199,7 +220,15 @@ type ProjectPublication = {
  * 
  * @param publicationDocId 
  * @returns array of <ProjectPublications>
- * this function is called within getProject to get all relevant publications for a project 
+ * this function is called within getProject to get all relevant publications for a project
+ * specifically this is called when "getAllData" is true in fetch projects
+ *  steps for this function
+ *   1. Select the base from airtable (in this case, "Project Publications")
+ *   2. Just find publications for a specific project- denoted by "publicationDocId"
+ *          Our "Project Publications" DB is organized by project, so each project has its own unique ID
+ *   3. Each publication is organized via "Publication_i_name" and "Publication_i_url", so we map i in range(1,5) to get each publication + url
+ *   4. Lastly, if there is both a name and a URL, we push that onto the "ProjectPublication" array
+ *   5. We resolve the promise w/ that array of ProjectPublications
  */
 export async function fetchPublications(
   publicationDocId: string

lib/sig.ts

@@ -4,8 +4,17 @@ import { Person, PartialPerson, fetchPeople, sortPeople } from "./people";
 import { Project, PartialProject, getProject } from "./project";
 /**
  * @typedef SIG
+ * @property {string} id: Id of the SIG, held by airtable- 
+ *      to find this value, click on an airtable field/SIG (from the SIGs database), and look at the URL at the part with the value ./recxxxxxx
+ *      the value of the SIG id is that recxxxx value from the URL
  * used to contain information for a given SIG, 
- * including sig ID(in airtable db), name, description, and banner image 
+ * @property {string} name: name of a SIG
+ * @property {string} description: Description of a SIG
+ * @property {string} banner_image: either the URL to the banner image, or Null (no banner image)
+ * @property {PartialPerson[]} members: array of information about members of a sig, including name, role, and if they're active
+ * @property {PartialProject[]} projects: array of information about projects in a sig, not including explainer images and publications
+ *  * including sig ID(in airtable db), name, description, and banner image 
+ * 
  */
 export type SIG = {
   id: string;
@@ -17,7 +26,23 @@ export type SIG = {
 };
 /**
  * @function fetchSigs()
- * fetches all SIGS from the Airtable DB
+ *  at a high level, fetches all SIGS from the Airtable DB
+ * steps: 
+ *  1. Select the base from airtable (in this case, "SIGS")
+ *  2. For each page (SIG)...
+ *  3. We get project info
+ *        3a. we get the project IDs for that sig, and then use those to get information about the projects
+ *        3b. we then map the information for all projects from 2a until it is trimmed, and we also do not keep the images/publications
+ * 4. And information about people
+ *        4a. We then get the students on each person in the SIG, including faculty, sigHeads, and members by filtering the result from getPeople
+ *        4b. We then sort these people such that the website displays Faculty -> Sigheads -> Others 
+ *        4b. We get the "others" from the set of people whose names are in fetchedMembers
+ * 5. We then subtract information from the array of People, keeping only information included in the PartialPerson type
+ *        this gets rid of bios specifically
+ * 6. Lastly we push this onto the results array
+ * 7. Continue steps 2-6 until this process is completed and all SIGS are pushed onto the results array
+ *
+ * 
  * @returns a promise that is resolved via an array of SIG[]
  */
 

pages/projects/index.tsx

@@ -5,7 +5,7 @@ import ReactMarkdown from "react-markdown";
 import TeamMembers from "../../components/people/TeamMembers";
 import { fetchSigs, SIG } from "../../lib/sig";
 import { revalidateTime } from "../../lib/consts";
-// promise from fetchSigs function 
+
 interface ProjectProps {
   sigs: SIG[];
 }