Merge pull request #1 from Waydriver/miguel-add-docs

Document some functions

src/data/tasks.ts

@@ -11,6 +11,11 @@ export const deleteTask = (id: TaskId) => {
   delete getData().tasks[id];
 };
 
+/**
+ * Given a project ID, return a list of tasks within it
+ * @param id ID of project
+ * @returns a list of tasks within this project
+ */
 export const getTasksInProject = (id: ProjectId): Task[] => {
   const tasks = [];
   for (const task of Object.values(getData().tasks)) {
@@ -53,6 +58,16 @@ export const findDirectSuccessorTasks = (id: TaskId): TaskId[] => {
   return successors;
 };
 
+/**
+ * Finds and returns an array containing all tasks that are a successor to this
+ * task.
+ *
+ * A successor task is a task that contains this task as a prerequisite, or
+ * contains a task for which this task is a successor.
+ *
+ * @param id ID of the task
+ * @returns array of task IDs that are successors to the given task
+ */
 export const findAllSuccessorTasks = (id: TaskId): TaskId[] => {
   const successors: TaskId[] = [];
   for (const task of Object.values(getData().tasks)) {
@@ -70,6 +85,12 @@ export const findAllSuccessorTasks = (id: TaskId): TaskId[] => {
   return successors;
 };
 
+/**
+ * Add a task as a prerequisite to another task
+ * @param task task object to add prerequisite to
+ * @param prereq task ID of prerequisite task
+ * @returns whether the task was already a prerequisite
+ */
 export const taskAddPrerequisite = (task: Task, prereq: TaskId): boolean => {
   if (task.prerequisites.includes(prereq)) {
     return false;

src/util/token.ts

@@ -15,6 +15,11 @@ export const getAccessTokenSecret = () => {
   return process.env.ACCESS_TOKEN_SECRET as string;
 };
 
+/**
+ * Generates a token for the given user
+ * @param id ID of user to generate token for
+ * @returns a new JWT token
+ */
 export const generateToken = (id: UserId) => {
   const sessionId = crypto.randomUUID();
   // INVESTIGATE: Do we need to hash our session IDs for storage?
@@ -30,6 +35,10 @@ export const generateToken = (id: UserId) => {
   );
 };
 
+/**
+ * Given a request, revoke the token associated with the request
+ * @param req Request object
+ */
 export const revokeToken = (req: JWTRequest) => {
   const { userId, sessionId } = req.auth as TokenData;
   const sessions = getData().users[userId].sessions;