From 99eccd455ddf40c03b1718a6d5bc91dacf002fa9 Mon Sep 17 00:00:00 2001
From: n0099 <n@n0099.net>
Date: Mon, 26 Feb 2024 04:29:26 +0800
Subject: [PATCH] * wrapping literal symbol references in comments with jsdoc
 `{@link }` $ mkdir list && mv *list.* list && mv list/{rendererList,index}.ts
 @ components/Post/renderers @ fe

---
 fe/src/api/index.ts                                |  3 ++-
 fe/src/components/Post/PostNav.vue                 |  2 +-
 fe/src/components/Post/PostPage.vue                |  2 +-
 fe/src/components/Post/queryForm/QueryForm.vue     |  2 +-
 fe/src/components/Post/queryForm/queryParams.ts    |  2 +-
 fe/src/components/Post/queryForm/useQueryForm.ts   | 12 +++++++-----
 .../Post/renderers/{ => list}/RendererList.vue     | 14 +++++++-------
 .../renderers/{rendererList.ts => list/index.ts}   |  6 +++---
 fe/src/router/index.ts                             |  2 +-
 fe/src/views/Post.vue                              |  2 +-
 10 files changed, 25 insertions(+), 22 deletions(-)
 rename fe/src/components/Post/renderers/{ => list}/RendererList.vue (97%)
 rename fe/src/components/Post/renderers/{rendererList.ts => list/index.ts} (88%)

diff --git a/fe/src/api/index.ts b/fe/src/api/index.ts
index b000c861..7cd565af 100644
--- a/fe/src/api/index.ts
+++ b/fe/src/api/index.ts
@@ -40,7 +40,8 @@ export const queryFunction = async <TResponse, TQueryParam>
             { headers: { Accept: 'application/json' }, signal }
         );
 
-        // must before any Response.text|json() to prevent `Failed to execute 'clone' on 'Response': Response body is already used`
+        /** must be cloned before any {@link Response.text()} */
+        // to prevent `Failed to execute 'clone' on 'Response': Response body is already used`
         const response2 = response.clone();
         const json = await response.json() as TResponse;
         if (isApiError(json))
diff --git a/fe/src/components/Post/PostNav.vue b/fe/src/components/Post/PostNav.vue
index ae3958de..62ddfd57 100644
--- a/fe/src/components/Post/PostNav.vue
+++ b/fe/src/components/Post/PostNav.vue
@@ -44,7 +44,7 @@
 <script setup lang="ts">
 import { isApiError } from '@/api/index';
 import type { ApiPosts, Cursor } from '@/api/index.d';
-import { getReplyTitleTopOffset } from '@/components/Post/renderers/rendererList';
+import { getReplyTitleTopOffset } from '@/components/Post/renderers/list';
 import type { Pid, Tid, ToPromise } from '@/shared';
 import { cursorTemplate, scrollBarWidth } from '@/shared';
 import { useElementRefsStore } from '@/stores/elementRefs';
diff --git a/fe/src/components/Post/PostPage.vue b/fe/src/components/Post/PostPage.vue
index fbcd1122..e2f60fb1 100644
--- a/fe/src/components/Post/PostPage.vue
+++ b/fe/src/components/Post/PostPage.vue
@@ -7,8 +7,8 @@
 </template>
 
 <script setup lang="ts">
-import RendererList from './renderers/RendererList.vue';
 import RendererTable from './renderers/RendererTable.vue';
+import RendererList from './renderers/list/RendererList.vue';
 
 import { PageCurrentButton, PageNextButton, useNextCursorRoute } from '../paginations/usePaginationButtons';
 import type { PostRenderer } from '@/views/Post.vue';
diff --git a/fe/src/components/Post/queryForm/QueryForm.vue b/fe/src/components/Post/queryForm/QueryForm.vue
index ce243922..d1e80005 100644
--- a/fe/src/components/Post/queryForm/QueryForm.vue
+++ b/fe/src/components/Post/queryForm/QueryForm.vue
@@ -329,7 +329,7 @@ const checkParams = async (): Promise<boolean> => {
     // check params required post types, index query doesn't restrict on post types
     invalidParamsIndex.value = []; // reset to prevent duplicate indexes
     if (currentQueryType !== 'postID' && currentQueryType !== 'fid') {
-        // we don't filter() here for post types validate
+        /** we don't {@link Array.filter()} here for post types validate */
         params.value.map(clearParamDefaultValue).forEach((param, paramIndex) => {
             if (param?.name === undefined || param.value === undefined) {
                 invalidParamsIndex.value.push(paramIndex);
diff --git a/fe/src/components/Post/queryForm/queryParams.ts b/fe/src/components/Post/queryForm/queryParams.ts
index a030d0bd..d0eb1d69 100644
--- a/fe/src/components/Post/queryForm/queryParams.ts
+++ b/fe/src/components/Post/queryForm/queryParams.ts
@@ -161,7 +161,7 @@ const useQueryFormDependency: Parameters<typeof useQueryForm>[0] = {
     }
 };
 
-// must get invoked with in the setup() of component
+/** must get invoked with in the {@link setup()} of component */
 export const useQueryFormWithUniqueParams = () => {
     const ret = useQueryForm<KnownUniqueParams, KnownParams>(useQueryFormDependency);
     ret.uniqueParams.value = {
diff --git a/fe/src/components/Post/queryForm/useQueryForm.ts b/fe/src/components/Post/queryForm/useQueryForm.ts
index e23a0950..db8ac92e 100644
--- a/fe/src/components/Post/queryForm/useQueryForm.ts
+++ b/fe/src/components/Post/queryForm/useQueryForm.ts
@@ -61,11 +61,12 @@ export default <
         if (defaultParam === undefined)
             throw new Error(`Param ${param.name} not found in paramsDefaultValue`);
 
-        // remove subParam.not: false, which previously added by fillParamDefaultValue()
+        /** remove subParam.not: false, which previously added by {@link fillParamDefaultValue()} */
         if (defaultParam.subParam !== undefined)
             defaultParam.subParam.not ??= false;
         const newParam: Partial<UnknownParam> = _.cloneDeep(param); // prevent mutating origin param
-        // number will consider as empty in isEmpty(), to prevent this we use complex short circuit evaluate expression
+        /** number will consider as empty in {@link _.isEmpty()} */
+        // to prevent this we use complex short circuit evaluate expression
         if (!(_.isNumber(newParam.value) || !_.isEmpty(newParam.value))
             || (_.isArray(newParam.value) && _.isArray(defaultParam.value)
 
@@ -85,15 +86,16 @@ export default <
         if (_.isEmpty(newParam.subParam))
             delete newParam.subParam;
 
-        return _.isEmpty(_.omit(newParam, 'name')) ? null : newParam; // return null for further filter()
+        /** return null for further {@link _.filter()} */
+        return _.isEmpty(_.omit(newParam, 'name')) ? null : newParam;
     };
     const clearedParamsDefaultValue = (): Array<Partial<Param>> =>
 
-        // filter() will remove falsy values like null
+        /** {@link _.filter()} will remove falsy values like null */
         _.filter(params.value.map(clearParamDefaultValue)) as Array<Partial<Param>>;
     const clearedUniqueParamsDefaultValue = (): Partial<UniqueParams> =>
 
-        // mapValues() return object which remains keys, pickBy() like filter() for objects
+        /** {@link _.mapValues()} return object which remains keys, {@link _.pickBy()} like {@link _.filter()} for objects */
         _.pickBy(_.mapValues(uniqueParams.value, clearParamDefaultValue)) as Partial<UniqueParams>;
     const removeUndefinedFromPartialObjectValues = <T extends Partial<T>, R>(object: Partial<T>) =>
         Object.values(object).filter(i => i !== undefined) as R[];
diff --git a/fe/src/components/Post/renderers/RendererList.vue b/fe/src/components/Post/renderers/list/RendererList.vue
similarity index 97%
rename from fe/src/components/Post/renderers/RendererList.vue
rename to fe/src/components/Post/renderers/list/RendererList.vue
index 6c4e4ead..03d6a472 100644
--- a/fe/src/components/Post/renderers/RendererList.vue
+++ b/fe/src/components/Post/renderers/list/RendererList.vue
@@ -152,12 +152,12 @@
 </template>
 
 <script setup lang="ts">
-import { baseGetUser, baseRenderUsername } from './common';
-import { postListItemScrollPosition } from './rendererList';
-import BadgePostTime from '../badges/BadgePostTime.vue';
-import BadgeThread from '../badges/BadgeThread.vue';
-import BadgeUser from '../badges/BadgeUser.vue';
-import PostCommonMetadataIconLinks from '../badges/PostCommonMetadataIconLinks.vue';
+import { postListItemScrollPosition } from './index';
+import { baseGetUser, baseRenderUsername } from '../common';
+import BadgePostTime from '@/components/Post/badges/BadgePostTime.vue';
+import BadgeThread from '@/components/Post/badges/BadgeThread.vue';
+import BadgeUser from '@/components/Post/badges/BadgeUser.vue';
+import PostCommonMetadataIconLinks from '@/components/Post/badges/PostCommonMetadataIconLinks.vue';
 
 import type { ApiPosts } from '@/api/index.d';
 import type { Reply, SubReply, Thread } from '@/api/post';
@@ -223,7 +223,7 @@ const posts = computed(() => {
 onMounted(initialTippy);
 onMounted(async () => {
     await nextTick();
-    const imageWidth = convertRemToPixels(18.75); // match with .tieba-image:max-inline-size in shread/tieba.css
+    const imageWidth = convertRemToPixels(18.75); // match with .tieba-image:max-inline-size in shared/tieba.css
 
     // block-size of .reply-content should be similar when author usernames are also similar, so only takes the first element
     const contentEl = document.querySelector<HTMLElement>('.reply-content');
diff --git a/fe/src/components/Post/renderers/rendererList.ts b/fe/src/components/Post/renderers/list/index.ts
similarity index 88%
rename from fe/src/components/Post/renderers/rendererList.ts
rename to fe/src/components/Post/renderers/list/index.ts
index 24ea3c57..363d6427 100644
--- a/fe/src/components/Post/renderers/rendererList.ts
+++ b/fe/src/components/Post/renderers/list/index.ts
@@ -17,12 +17,12 @@ export const postListItemScrollPosition = (route: RouteLocationNormalized)
     };
 };
 const scrollToPostListItem = (el: Element) => {
-    // simply invoke el.scrollIntoView() for only once will scroll the element to the top of the viewport
+    /** simply invoke {@link Element.scrollIntoView()} for only once will scroll the element to the top of the viewport */
     // and then some other elements above it such as img[loading='lazy'] may change its box size
     // that would lead to reflow resulting in the element being pushed down or up out of viewport
-    // due to document.scrollingElement.scrollTop changed a lot
+    /** due to {@link document.scrollingElement.scrollTop()} changed a lot */
     const tryScroll = () => {
-        // not using a passive callback by IntersectionObserverto to prevent getBoundingClientRect() caused force reflow
+        /** not using a passive callback by IntersectionObserverto to prevent {@link Element.getBoundingClientRect()} caused force reflow */
         // due to it will only emit once the configured thresholds are reached
         // thus the top offset might be far from 0 that is top aligned with viewport when the callback is called
         // since the element is still near the bottom of viewport at that point of time
diff --git a/fe/src/router/index.ts b/fe/src/router/index.ts
index 6dbb6b96..262fae76 100644
--- a/fe/src/router/index.ts
+++ b/fe/src/router/index.ts
@@ -123,7 +123,7 @@ export default createRouter({
 
         if (to.hash)
             return { el: to.hash, top: 0 };
-        if (from.name !== undefined) { // from.name will be undefined when user refresh page
+        if (from.name !== undefined) { // when user refresh page
             assertRouteNameIsStr(to.name);
             assertRouteNameIsStr(from.name);
 
diff --git a/fe/src/views/Post.vue b/fe/src/views/Post.vue
index 07cfeae7..b892f00f 100644
--- a/fe/src/views/Post.vue
+++ b/fe/src/views/Post.vue
@@ -34,7 +34,7 @@ import PlaceholderPostList from '@/components/placeholders/PlaceholderPostList.v
 
 import { useApiPosts } from '@/api';
 import type { ApiPosts, Cursor } from '@/api/index.d';
-import { scrollToPostListItemByRoute } from '@/components/Post/renderers/rendererList';
+import { scrollToPostListItemByRoute } from '@/components/Post/renderers/list/index';
 import { compareRouteIsNewQuery, getRouteCursorParam } from '@/router';
 import type { ObjUnknown } from '@/shared';
 import { notyShow, scrollBarWidth, titleTemplate } from '@/shared';