From 31e8bb9cfb28887da088a860ff54cd96a211d21f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jind=C5=99ich=20B=C3=A4r?= <jindrichbar@gmail.com>
Date: Wed, 11 Dec 2024 14:55:00 +0100
Subject: [PATCH] docs: add function docstrings

---
 apify-docs-theme/src/markdown.js | 43 +++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/apify-docs-theme/src/markdown.js b/apify-docs-theme/src/markdown.js
index 5d2c41be9..ad06110ea 100644
--- a/apify-docs-theme/src/markdown.js
+++ b/apify-docs-theme/src/markdown.js
@@ -1,5 +1,10 @@
 const { remark } = require('remark');
 
+/**
+ * Updates the markdown content for better UX and compatibility with Docusaurus v3.
+ * @param {string} changelog The markdown content.
+ * @returns {string} The updated markdown content.
+ */
 function updateChangelog(changelog) {
     const tree = remark.parse(changelog);
 
@@ -13,6 +18,13 @@ function updateChangelog(changelog) {
     return changelog;
 }
 
+/**
+ * Bumps the headings levels in the markdown content. This function increases the depth
+ * of all headings in the content by 1. This is useful when the content is included in
+ * another markdown file with a higher-level heading.
+ * @param {*} tree Remark AST tree.
+ * @returns {void} Nothing. This function modifies the tree in place.
+ */
 function bumpHeadingsLevels(tree) {
     tree.children?.forEach((child) => {
         if (child.type === 'heading') {
@@ -23,6 +35,12 @@ function bumpHeadingsLevels(tree) {
     });
 }
 
+/**
+ * Links user tags in the markdown content. This function replaces the user tags
+ * (e.g. `@username`) with a link to the user's GitHub profile (just like GitHub's UI).
+ * @param {*} tree Remark AST tree.
+ * @returns {void} Nothing. This function modifies the tree in place.
+ */
 function linkifyUserTags(tree) {
     for (let i = 0; i < tree.children?.length; i++) {
         const child = tree.children[i];
@@ -56,7 +74,12 @@ function linkifyUserTags(tree) {
     }
 }
 
-// If there is a PR URL (https://github.com/**/**/pull/number) in the text body, split the body, and replace the URL with a link to the PR (the text should be the PR number).
+/**
+ * Prettifies PR links in the markdown content. Just like GitHub's UI, this function
+ * replaces the full PR URL with a link represented by the PR number (prefixed by a hashtag).
+ * @param {*} tree Remark AST tree.
+ * @returns {void} Nothing. This function modifies the tree in place.
+ */
 function prettifyPRLinks(tree) {
     for (let i = 0; i < tree.children?.length; i++) {
         const child = tree.children[i];
@@ -90,15 +113,27 @@ function prettifyPRLinks(tree) {
     }
 }
 
-function addFrontmatter(changelog, header = 'Changelog') {
+/**
+ * Adds frontmatter to the markdown content.
+ * @param {string} changelog The markdown content.
+ * @param {string} title The frontmatter title.
+ * @returns {string} The markdown content with frontmatter.
+ */
+function addFrontmatter(changelog, title = 'Changelog') {
     return `---
-title: ${header}
-sidebar_label: ${header}
+title: ${title}
+sidebar_label: ${title}
 toc_max_heading_level: 3
 ---
 ${changelog}`;
 }
 
+/**
+ * Escapes the MDX-related characters in the markdown content.
+ * This is required by Docusaurus v3 and its dependencies (see the v3 [migration guide](https://docusaurus.io/docs/migration/v3#common-mdx-problems)).
+ * @param {string} changelog The markdown content.
+ * @returns {string} The markdown content with escaped MDX characters.
+ */
 function escapeMDXCharacters(changelog) {
     return changelog.replaceAll(/<|>/g, (match) => {
         return match === '<' ? '&lt;' : '&gt;';