Merge pull request #106 from arnaugomez/feat/docs

Add docs and upgrade dependencies

.nvmrc

@@ -1 +1 @@
-v20.14.0
+v20.15.0

app/(admin-layout)/courses/detail/[id]/export/anki/route.ts

@@ -5,6 +5,9 @@ import type { PropsWithIdParam } from "@/src/common/ui/models/props-with-id-para
 import { CourseDoesNotExistError } from "@/src/courses/domain/models/course-errors";
 import { fetchMyProfile } from "@/src/profile/ui/fetch/fetch-my-profile";
 
+/**
+ * Returns a txt file with the notes of a course in Anki (plain text) format.
+ */
 export async function GET(_: Request, { params: { id } }: PropsWithIdParam) {
   try {
     const profile = await fetchMyProfile();

app/(admin-layout)/courses/detail/[id]/export/csv/route.ts

@@ -6,6 +6,9 @@ import { CourseDoesNotExistError } from "@/src/courses/domain/models/course-erro
 import { fetchMyProfile } from "@/src/profile/ui/fetch/fetch-my-profile";
 import { stringify } from "csv-stringify/sync";
 
+/**
+ * Returns a CSV file with the notes of a course in CSV format.
+ */
 export async function GET(_: Request, { params: { id } }: PropsWithIdParam) {
   try {
     const profile = await fetchMyProfile();

app/(admin-layout)/courses/detail/[id]/export/json/route.ts

@@ -5,6 +5,9 @@ import type { PropsWithIdParam } from "@/src/common/ui/models/props-with-id-para
 import { CourseDoesNotExistError } from "@/src/courses/domain/models/course-errors";
 import { fetchMyProfile } from "@/src/profile/ui/fetch/fetch-my-profile";
 
+/**
+ * Route handler that returns a JSON file with the notes of a course, in JSON format.
+ */
 export async function GET(_: Request, { params: { id } }: PropsWithIdParam) {
   try {
     const profile = await fetchMyProfile();

app/(admin-layout)/courses/detail/[id]/page.tsx

@@ -8,6 +8,12 @@ import { fetchMyProfile } from "@/src/profile/ui/fetch/fetch-my-profile";
 import type { Metadata } from "next";
 import { notFound } from "next/navigation";
 
+/**
+ * Shows detailed data of a course.
+ *
+ * This component is also responsible for getting the data of the course
+ * and checking that the profile has access rights to the course
+ */
 export default async function CourseDetailPage({
   params: { id },
 }: PropsWithIdParam) {
@@ -30,6 +36,9 @@ export default async function CourseDetailPage({
   );
 }
 
+/**
+ * Generates the data inside the head tag of the HTML document, for the course detail page.
+ */
 export async function generateMetadata({
   params: { id },
 }: PropsWithIdParam): Promise<Metadata> {

app/(admin-layout)/courses/detail/[id]/practice/loading.tsx

@@ -2,6 +2,9 @@ import { textStyles } from "@/src/common/ui/styles/text-styles";
 import { cn } from "@/src/common/ui/utils/shadcn";
 import { GraduationCap } from "lucide-react";
 
+/**
+ * Shows a loading indicator while the practice page is being loaded.
+ */
 export default function PracticeLoadingPage() {
   return (
     <div className="flex size-full flex-col items-center justify-center space-y-2">

app/(admin-layout)/courses/detail/[id]/practice/page.tsx

@@ -10,6 +10,12 @@ export const metadata: Metadata = {
   title: "Practicar curso",
 };
 
+/**
+ * Shows an interactive practice page for a course, where the user
+ * can practice the cards of the course.
+ *
+ * Before showing the practice page, it loads the data of the cards.
+ */
 export default async function PracticePage({
   params: { id },
 }: PropsWithIdParam) {

app/(admin-layout)/error.tsx

@@ -9,6 +9,9 @@ import { CircleX } from "lucide-react";
 import Link from "next/link";
 import { useEffect } from "react";
 
+/**
+ * Shows an error message that is displayed in the pages with the Admin layout.
+ */
 export default function ErrorPage({ error, reset }: ErrorPageProps) {
   useEffect(() => {
     clientLocator.ErrorTrackingService().captureError(error);

app/(admin-layout)/layout.tsx

@@ -1,5 +1,9 @@
 import { Navbar } from "@/src/common/ui/navbar/components/navbar";
 
+/**
+ * Layout for pages that have a fixed size that is equal to the width and height
+ * of the browser screen. The main body does not have scroll in these pages.
+ */
 export default function AdminLayout({
   children,
 }: Readonly<{

app/(navbar-layout)/(login-guard)/courses/detail/[id]/ai-generator/page.tsx

@@ -20,6 +20,9 @@ export const metadata: Metadata = {
   title: "Generador AI",
 };
 
+/**
+ * Shows the AI generator section for a given course
+ */
 export default async function CourseAiGeneratorPage({
   params: { id },
 }: PropsWithIdParam) {

app/(navbar-layout)/(login-guard)/courses/page.tsx

@@ -16,15 +16,16 @@ export const metadata: Metadata = {
   title: "Mis cursos",
 };
 
+/**
+ * Shows a list of courses that the profile has created or enrolled in.
+ */
 export default function CoursesPage({
   searchParams,
 }: {
   searchParams?: {
     page?: string;
   };
 }) {
-  const page = Number(searchParams?.page) || 1;
-
   return (
     <main>
       <div className="h-20" />
@@ -37,7 +38,7 @@ export default function CoursesPage({
         </div>
       </div>
       <div className="h-10" />
-      <CoursesPageContent page={page} />
+      <CoursesPageLoader page={Number(searchParams?.page) || 1} />
     </main>
   );
 }
@@ -46,7 +47,10 @@ interface CoursesPageContentProps {
   page: number;
 }
 
-async function CoursesPageContent({ page }: CoursesPageContentProps) {
+/**
+ * Gets the data of the list of courses that the profile has created or enrolled in.
+ */
+async function CoursesPageLoader({ page }: CoursesPageContentProps) {
   const profile = await fetchMyProfile();
   if (!profile) {
     return null;

app/(navbar-layout)/(login-guard)/home/page.tsx

@@ -10,6 +10,9 @@ export const metadata: Metadata = {
   title: "Inicio",
 };
 
+/**
+ * Shows the home page.
+ */
 export default async function HomePage() {
   const profile = await fetchMyProfile();
   if (!profile) {
@@ -22,12 +25,16 @@ export default async function HomePage() {
       <HomeGreeting />
 
       <div className="h-6" />
-      {hasCourses ? <HomePageContent /> : <CreateCourseCtaLarge />}
+      {hasCourses ? <HomePageSections /> : <CreateCourseCtaLarge />}
     </main>
   );
 }
 
-function HomePageContent() {
+/**
+ * Shows the different sections of the home page that should show up when the
+ * user has already created or enrolled in a course
+ */
+function HomePageSections() {
   return (
     <>
       <KeepLearningSection />

app/(navbar-layout)/(login-guard)/layout.tsx

@@ -1,6 +1,10 @@
 import { fetchSession } from "@/src/auth/ui/fetch/fetch-session";
 import { redirect } from "next/navigation";
 
+/**
+ * Checks that the user is logged in and has verified the email. Otherwise, it
+ * redirects to the landing page or to the email verification page.
+ */
 async function loginGuard() {
   const result = await fetchSession();
   if (!result.session) {
@@ -10,6 +14,10 @@ async function loginGuard() {
     redirect("/auth/verify-email");
   }
 }
+
+/**
+ * Applies the `loginGuard` guard to the pages inside this layout
+ */
 export default async function LoginGuardLayout({
   children,
 }: Readonly<{

app/(navbar-layout)/(login-guard)/learn/page.tsx

@@ -12,6 +12,10 @@ export const metadata: Metadata = {
   title: "Aprender",
 };
 
+/**
+ * Page that shows the courses that the profile has enrolled in
+ * and suggests a variety of learning activities.
+ */
 export default async function LearnPage() {
   return (
     <main>
@@ -30,6 +34,10 @@ export default async function LearnPage() {
   );
 }
 
+/**
+ * This component shows the content of the Learn page if the user has enrolled
+ * in some courses. Otherwise, it shows a call to action to create a course.
+ */
 async function LearnPageContent() {
   const courses = await fetchMyCoursesPreview();
   if (courses.length === 0) {

app/(navbar-layout)/(login-guard)/profile/page.tsx

@@ -3,6 +3,9 @@ import { locator } from "@/src/common/di/locator";
 import { getProfilePagePath } from "@/src/profile/ui/utils/get-profile-page-path";
 import { RedirectType, notFound, redirect } from "next/navigation";
 
+/**
+ * Route that redirects to the page of the profile of the current user
+ */
 export default async function MyProfilePage() {
   const { user } = await fetchSession();
   if (!user) notFound();

app/(navbar-layout)/(login-guard)/settings/page.tsx

@@ -13,6 +13,9 @@ export const metadata: Metadata = {
   title: "Ajustes",
 };
 
+/**
+ * Gets the data of the settings page and shows it
+ */
 export default async function SettingsPage() {
   const { user } = await fetchSession();
   if (!user) notFound();
@@ -23,6 +26,9 @@ interface SettingsPageLoadedProps {
   user: UserModel;
 }
 
+/**
+ * Shows the data of the settings page, with all its options.
+ */
 function SettingsPageLoaded({ user }: SettingsPageLoadedProps) {
   return (
     <main>

app/(navbar-layout)/discover/page.tsx

@@ -13,6 +13,10 @@ export const metadata: Metadata = {
   title: "Explorar cursos",
 };
 
+/**
+ * Page that contains a search bar and a list of search results. The search
+ * results are a list of courses.
+ */
 export default async function DiscoverPage({
   searchParams,
 }: {

app/(navbar-layout)/error.tsx

@@ -2,6 +2,10 @@
 import type { ErrorPageProps } from "@/src/common/ui/models/props-with-error";
 import ErrorPage from "../(admin-layout)/error";
 
+/**
+ * Displays a page with an error message. Is shown when an error occurs in the pages
+ * within the `NavbarLayout` component.
+ */
 export default function NavbarLayoutErrorPage(props: ErrorPageProps) {
   return (
     <div className="relative h-[80vh]">

app/(navbar-layout)/layout.tsx

@@ -2,6 +2,10 @@ import { Footer } from "@/src/common/ui/components/footer/footer";
 import { Navbar } from "@/src/common/ui/navbar/components/navbar";
 import type { PropsWithChildren } from "react";
 
+/**
+ * Basic layout of the app. It contains a navbar, a body and a footer. This layout is used in pages that
+ * have got scroll in the main body element.
+ */
 export default function NavbarLayout({ children }: PropsWithChildren) {
   return (
     <>

app/(navbar-layout)/page.tsx

@@ -2,7 +2,11 @@ import { LandingAdvantagesSection } from "@/src/landing/ui/components/landing-ad
 import { LandingFaq } from "@/src/landing/ui/components/landing-faq";
 import { LandingHero } from "@/src/landing/ui/components/landing-hero";
 
-export default function Landing() {
+/**
+ * Displays the Landing page. This page contains basic information about the platform
+ * and call to action to become a user.
+ */
+export default function LandingPage() {
   return (
     <main>
       <LandingHero />

app/(navbar-layout)/profile/[handle]/page.tsx

@@ -5,6 +5,9 @@ import { fetchProfileByHandle } from "@/src/profile/ui/fetch/fetch-profile-by-ha
 import type { Metadata } from "next";
 import { notFound } from "next/navigation";
 
+/**
+ * Gets the data of the profile with the given handle and shows the profile page
+ */
 export default async function ProfileByHandlePage({
   params: { handle },
 }: PropsWithHandleParam) {
@@ -14,6 +17,9 @@ export default async function ProfileByHandlePage({
   return <ProfilePage profile={profile} />;
 }
 
+/**
+ * Returns the metadata of the HTML head for the profile page
+ */
 export async function generateMetadata({
   params: { handle },
 }: PropsWithHandleParam): Promise<Metadata> {

app/api/cron/file-uploads/delete-outdated/route.ts

@@ -1,6 +1,10 @@
 import { locator } from "@/src/common/di/locator";
 import { ApiErrorHandler } from "@/src/common/ui/api/api-error-handler";
 
+/**
+ * Deletes all the files from the external storage service that are no longer in
+ * use. It is expected to be called frequently by a cron job process.
+ */
 export async function GET() {
   try {
     const repository = await locator.FileUploadsRepository();

app/auth/(logout-guard)/forgot-password/page.tsx

@@ -6,6 +6,11 @@ export const metadata: Metadata = {
   title: "Recupera tu cuenta",
 };
 
+/**
+ * This page is visited when the user has forgotten its credentials and wants to
+ * recover their account. It shows a form that, when submitted, sends a password
+ * restoration email to the user.
+ */
 export default function ForgotPasswordPage() {
   return (
     <>

app/auth/(logout-guard)/layout.tsx

@@ -2,6 +2,10 @@ import { fetchSession } from "@/src/auth/ui/fetch/fetch-session";
 import { redirect } from "next/navigation";
 import type { PropsWithChildren } from "react";
 
+/**
+ * Checks that the user is logged out. Otherwise, it redirects to the home page
+ * (if the email is verified) or to the email verification page.
+ */
 async function logoutGuard() {
   const result = await fetchSession();
   if (result.session) {
@@ -11,6 +15,10 @@ async function logoutGuard() {
     redirect("/auth/verify-email");
   }
 }
+
+/**
+ * Applies the `logoutGuard` guard to all the pages inside this layout.
+ */
 export default async function LogoutGuardLayout({
   children,
 }: PropsWithChildren) {

app/auth/(logout-guard)/login/page.tsx

@@ -6,6 +6,9 @@ export const metadata: Metadata = {
   title: "Login",
 };
 
+/**
+ * Renders a welcome message and a login form
+ */
 export default function LoginPage() {
   return (
     <>