From 1ed66142af32473885de147592142db0b7b091f2 Mon Sep 17 00:00:00 2001 From: n0099 Date: Mon, 26 Feb 2024 04:29:26 +0800 Subject: [PATCH] * wrapping literal symbol references in comments with jsdoc `{@link }` @ fe --- fe/src/api/index.ts | 3 ++- fe/src/components/Post/queryForm/QueryForm.vue | 2 +- fe/src/components/Post/queryForm/queryParams.ts | 2 +- fe/src/components/Post/queryForm/useQueryForm.ts | 12 +++++++----- fe/src/components/Post/renderers/RendererList.vue | 2 +- fe/src/components/Post/renderers/rendererList.ts | 6 +++--- fe/src/router/index.ts | 2 +- 7 files changed, 16 insertions(+), 13 deletions(-) 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 { 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/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 => { // 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[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(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 = _.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> => - // filter() will remove falsy values like null + /** {@link _.filter()} will remove falsy values like null */ _.filter(params.value.map(clearParamDefaultValue)) as Array>; const clearedUniqueParamsDefaultValue = (): Partial => - // 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; const removeUndefinedFromPartialObjectValues = , R>(object: Partial) => 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/RendererList.vue index 6c4e4ead..7233b234 100644 --- a/fe/src/components/Post/renderers/RendererList.vue +++ b/fe/src/components/Post/renderers/RendererList.vue @@ -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('.reply-content'); diff --git a/fe/src/components/Post/renderers/rendererList.ts b/fe/src/components/Post/renderers/rendererList.ts index 24ea3c57..363d6427 100644 --- a/fe/src/components/Post/renderers/rendererList.ts +++ b/fe/src/components/Post/renderers/rendererList.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);