docs: consolidate docs (#2182)

Signed-off-by: Philip Molares <philip.molares@udo.edu>

src/components/render-page/hooks/sync-scroll/use-document-sync-scrolling.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -11,6 +11,18 @@ import type { ScrollState } from '../../../editor-page/synced-scroll/scroll-prop
 import { useOnUserScroll } from './use-on-user-scroll'
 import { useScrollToLineMark } from './use-scroll-to-line-mark'
 
+/**
+ * Synchronizes the scroll status of the given container with the given scroll state and posts changes if the user scrolls.
+ *
+ * @param outerContainerRef A reference for the outer container.
+ * @param rendererRef A reference for the renderer
+ * @param numberOfLines The number of lines
+ * @param scrollState The current {@link ScrollState}
+ * @param onScroll A callback that posts new scroll states
+ * @return A tuple of two callbacks.
+ *         The first one should be executed if the {@link LineMarkerPosition line marker positions} are updated.
+ *         The second one should be executed if the user actually scrolls. Usually it should be attached to the DOM element that the user scrolls.
+ */
 export const useDocumentSyncScrolling = (
   outerContainerRef: React.RefObject<HTMLElement>,
   rendererRef: React.RefObject<HTMLElement>,

src/components/render-page/hooks/sync-scroll/use-on-user-scroll.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -9,6 +9,14 @@ import { useCallback } from 'react'
 import type { LineMarkerPosition } from '../../../markdown-renderer/markdown-extension/linemarker/types'
 import type { ScrollState } from '../../../editor-page/synced-scroll/scroll-props'
 
+/**
+ * Provides a callback to handle user scrolling.
+ *
+ * @param lineMarks An array of the current {@link LineMarkerPosition LineMarkerPositions}
+ * @param scrollContainer The container to scroll in
+ * @param onScroll A callback that posts new scroll states.
+ * @return A callback that can be called when the user is scrolling.
+ */
 export const useOnUserScroll = (
   lineMarks: LineMarkerPosition[] | undefined,
   scrollContainer: React.RefObject<HTMLElement>,

src/components/render-page/hooks/sync-scroll/use-scroll-to-line-mark.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -10,6 +10,14 @@ import type { LineMarkerPosition } from '../../../markdown-renderer/markdown-ext
 import type { ScrollState } from '../../../editor-page/synced-scroll/scroll-props'
 import { findLineMarks } from '../../../editor-page/synced-scroll/utils'
 
+/**
+ * Scrolls the given container to the correct {@link LineMarkerPosition}.
+ *
+ * @param scrollState The current {@link ScrollState}
+ * @param lineMarks An array of the current {@link LineMarkerPosition LineMarkerPositions}.
+ * @param contentLineCount The number of lines
+ * @param scrollContainer The container to scroll in
+ */
 export const useScrollToLineMark = (
   scrollState: ScrollState | undefined,
   lineMarks: LineMarkerPosition[] | undefined,

src/components/render-page/hooks/use-image-click-handler.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -10,6 +10,12 @@ import type { ImageClickHandler } from '../../markdown-renderer/markdown-extensi
 import type { RendererToEditorCommunicator } from '../window-post-message-communicator/renderer-to-editor-communicator'
 import { CommunicationMessageType } from '../window-post-message-communicator/rendering-message'
 
+/**
+ * Generates a callback to send information about a clicked image from the iframe back to the editor.
+ *
+ * @param iframeCommunicator The communicator to send the message with.
+ * @return The callback to give to on onClick handler
+ */
 export const useImageClickHandler = (iframeCommunicator: RendererToEditorCommunicator): ImageClickHandler => {
   return useCallback(
     (event: React.MouseEvent<HTMLImageElement, MouseEvent>) => {

src/components/render-page/iframe-markdown-renderer.tsx

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -19,6 +19,9 @@ import { SlideshowMarkdownRenderer } from '../markdown-renderer/slideshow-markdo
 import { initialState } from '../../redux/note-details/initial-state'
 import type { RendererFrontmatterInfo } from '../../redux/note-details/types/note-details'
 
+/**
+ * Wraps the markdown rendering in an iframe.
+ */
 export const IframeMarkdownRenderer: React.FC = () => {
   const [markdownContentLines, setMarkdownContentLines] = useState<string[]>([])
   const [scrollState, setScrollState] = useState<ScrollState>({ firstLineInView: 1, scrolledPercentage: 0 })

src/components/render-page/markdown-document.tsx

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -37,6 +37,24 @@ export interface MarkdownDocumentProps extends RendererProps {
   frontmatterInfo?: RendererFrontmatterInfo
 }
 
+/**
+ * Renders a markdown document and handles scrolling, yaml metadata and a floating table of contents.
+ *
+ * @param additionalOuterContainerClasses Additional classes given to the outer container directly
+ * @param additionalRendererClasses Additional classes given {@link DocumentMarkdownRenderer} directly
+ * @param onFirstHeadingChange The callback to call when the first heading changes.
+ * @param onMakeScrollSource The callback to call if a change of the scroll source is requested-
+ * @param onTaskCheckedChange The callback to call if a task get's checked or unchecked.
+ * @param baseUrl The base url for the renderer
+ * @param markdownContentLines The current content of the markdown document.
+ * @param onImageClick The callback to call if an image is clicked.
+ * @param onScroll The callback to call if the renderer is scrolling.
+ * @param scrollState The current {@link ScrollState}
+ * @param onHeightChange The callback to call if the height of the document changes
+ * @param disableToc If the table of contents should be disabled.
+ * @param frontmatterInfo The frontmatter information for the renderer.
+ * @see https://markdown-it.github.io/
+ */
 export const MarkdownDocument: React.FC<MarkdownDocumentProps> = ({
   additionalOuterContainerClasses,
   additionalRendererClasses,

src/components/render-page/markdown-toc-button/table-of-contents-hovering-button.tsx

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -21,7 +21,6 @@ export interface MarkdownTocButtonProps {
  *
  * @param tocAst the {@link TocAst AST} that should be rendered.
  * @param baseUrl the base url that will be used to generate the links
- * @return the created component
  */
 export const TableOfContentsHoveringButton: React.FC<MarkdownTocButtonProps> = ({ tocAst, baseUrl }) => {
   return (

src/components/render-page/width-based-table-of-contents.tsx

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -24,7 +24,6 @@ const MAX_WIDTH_FOR_BUTTON_VISIBILITY = 1100
  * @param tocAst the {@link TocAst AST} that should be rendered.
  * @param width the width that should be used to determine if the button should be shown.
  * @param baseUrl the base url that will be used to generate the links //TODO: replace with consumer/provider
- * @return the created component
  */
 export const WidthBasedTableOfContents: React.FC<DocumentExternalTocProps> = ({ tocAst, width, baseUrl }) => {
   if (width >= MAX_WIDTH_FOR_BUTTON_VISIBILITY) {

src/components/render-page/window-post-message-communicator/hooks/use-is-renderer-ready.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -7,6 +7,8 @@
 import { useApplicationState } from '../../../../hooks/common/use-application-state'
 
 /**
- * Returns the current ready status of the renderer.
+ * Extracts the ready status of the renderer from the global application state.
+ *
+ * @return The current ready status of the renderer.
  */
 export const useIsRendererReady = (): boolean => useApplicationState((state) => state.rendererStatus.rendererReady)

src/components/render-page/window-post-message-communicator/hooks/use-send-to-renderer.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -10,6 +10,11 @@ import { useEditorToRendererCommunicator } from '../../../editor-page/render-con
 import type { MessagePayload } from '../window-post-message-communicator'
 import { useEffectOnRendererReady } from './use-effect-on-renderer-ready'
 
+/**
+ * Sends the given message to the renderer.
+ *
+ * @param message The message to send
+ */
 export const useSendToRenderer = (
   message: undefined | Extract<CommunicationMessages, MessagePayload<EditorToRendererMessageType>>
 ): void => {

src/components/render-page/window-post-message-communicator/window-post-message-communicator.ts

@@ -67,9 +67,9 @@ export abstract class WindowPostMessageCommunicator<
    * Sets the target for message sending.
    * Messages can be sent as soon as the communication is enabled.
    *
-   * @see enableCommunication
    * @param otherSide The target {@link Window} that should receive the messages.
    * @param otherOrigin The origin from the URL of the target. If this isn't correct then the message sending will produce CORS errors.
+   * @see enableCommunication
    */
   public setMessageTarget(otherSide: Window, otherOrigin: string): void {
     this.messageTarget = otherSide
@@ -128,7 +128,7 @@ export abstract class WindowPostMessageCommunicator<
    * Receives the message events and calls the handler that is mapped to the correct type.
    *
    * @param event The received event
-   * @return {@code true} if the event was processed.
+   * @return {@link true} if the event was processed.
    */
   protected handleEvent(event: MessageEvent<MessagePayload<RECEIVE_TYPE>>): void {
     Optional.ofNullable(event.data).ifPresent((payload) => {

src/components/render-page/word-counter.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -14,8 +14,9 @@ const EXCLUDED_CLASSES = ['katex-mathml']
 /**
  * Checks whether the given node is an excluded HTML tag and therefore should be
  * excluded from counting.
+ *
  * @param node The node to test.
- * @return true if the node should be excluded, false otherwise.
+ * @return {@link true} if the node should be excluded, {@link false} otherwise.
  */
 const isExcludedTag = (node: Element | ChildNode): boolean => {
   return EXCLUDED_TAGS.includes(node.nodeName.toLowerCase())
@@ -24,8 +25,9 @@ const isExcludedTag = (node: Element | ChildNode): boolean => {
 /**
  * Checks whether the given node is a HTML element with an excluded class name,
  * so that it should be excluded.
+ *
  * @param node The node to test.
- * @return true if the node should be excluded, false otherwise.
+ * @return {@link true} if the node should be excluded, {@link false} otherwise.
  */
 const isExcludedClass = (node: Element | ChildNode): boolean => {
   return EXCLUDED_CLASSES.some((excludedClass) => (node as HTMLElement).classList?.contains(excludedClass))
@@ -33,7 +35,8 @@ const isExcludedClass = (node: Element | ChildNode): boolean => {
 
 /**
  * Counts the words of the given node while ignoring empty nodes and excluded
- * nodes. Child nodes will recursively counted as well.
+ * nodes. Child nodes will recursively be counted as well.
+ *
  * @param node The node whose content's words should be counted.
  * @return The number of words counted in this node and its children.
  */