Merge pull request #101 from 4lex0017/docs_Fe

docs: more docs for fe

.gitignore

@@ -167,4 +167,4 @@ test_output/
 !build.spec
 **/.vitepress/cache
 docs/frontend/components/**
-docs/frontend/composables/**
+# docs/frontend/composables/**

docs/.vitepress/config.mts

@@ -1,12 +1,21 @@
 import path from 'node:path'
 import fs from 'node:fs'
 import { defineConfig } from 'vitepress'
+import { genTsDocs } from './scripts'
 
+/**
+ * Paths
+ */
 const projectPath = path.resolve(__filename, '..', '..', '..')
-const docsFrontendPath = path.join(projectPath, 'docs', 'frontend')
+
 const srcFrontendPath = path.join(projectPath, 'src', 'frontend')
+const srcComposablesPath = path.join(srcFrontendPath, 'composables')
+
+const docsFrontendPath = path.join(projectPath, 'docs', 'frontend')
+const docsComponentsPath = path.join(docsFrontendPath, 'components')
+const docsComposablesPath = path.join(docsFrontendPath, 'composables')
 
-const docsComponents = fs.readdirSync(path.join(docsFrontendPath, 'components'))
+const docsComponents = fs.readdirSync(docsComponentsPath)
 const componentsSidebarItems = docsComponents
   .filter((f) => {
     const [name, ext] = f.split('.')
@@ -16,6 +25,21 @@ const componentsSidebarItems = docsComponents
     return { text: name, link: `/${name}` }
   })
 
+const srcComposables = fs.readdirSync(srcComposablesPath)
+genTsDocs({
+  dirPath: docsComposablesPath,
+  inputFiles: srcComposables.map(f => path.join(srcComposablesPath, f)),
+})
+const docsComposables = fs.readdirSync(docsComposablesPath)
+const composablesSidebarItems = docsComposables
+  .filter((f) => {
+    const [name, ext] = f.split('.')
+    return name !== 'index' && ext === 'md'
+  }).map((f) => {
+    const name = f.split('.')[0]
+    return { text: name, link: `/${name}` }
+  })
+
 export default defineConfig({
   lang: 'en-US',
   title: 'AudioSplitter',
@@ -61,7 +85,7 @@ export default defineConfig({
             text: 'Composables',
             base: '/frontend/composables',
             collapsed: false,
-            items: [],
+            items: composablesSidebarItems,
           },
         ],
       },

docs/.vitepress/scripts.ts

@@ -0,0 +1,54 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import type { DocEntry } from 'tsdoc-markdown'
+import { buildDocumentation } from 'tsdoc-markdown'
+
+export function genTsDocs({ dirPath, inputFiles }: { inputFiles: string[]; dirPath: string }) {
+  const entries = buildDocumentation({ inputFiles })
+
+  if (!existsSync(dirPath))
+    mkdirSync(dirPath)
+
+  entries.forEach((entry) => {
+    const md = genMD(entry)
+    const targetPath = path.join(dirPath, `${entry.name}.md`)
+    writeFileSync(targetPath, md, { flag: 'w' })
+  })
+}
+
+function genMD(entry: DocEntry) {
+  // entry.name === 'useRandomColor' && console.log(JSON.stringify(entry, null, 4))
+  const md = []
+
+  md.push(`# ${entry.name}`)
+  md.push(`${entry.documentation}`)
+
+  const params = entry.jsDocs.filter(d => d.name === 'param')
+  if (params.length) {
+    md.push('## Parameters')
+    md.push('| Name | Description |')
+    md.push('|------|-------------|')
+
+    params.forEach((d) => {
+      const [name, desc] = d.text.filter(t => t.kind !== 'space')
+      md.push(`|${name?.text}|${desc?.text}|`)
+    })
+  }
+
+  // TODO Make this section better
+  if (entry.type) {
+    const returns = entry.jsDocs.find(d => d.name === 'returns')
+
+    md.push('## Returns')
+    md.push(returns?.text?.[0]?.text)
+    md.push(`\`\`\`\n${entry.type}\n\`\`\``)
+  }
+
+  const examples = entry.jsDocs.filter(d => d.name === 'example')
+  if (examples.length) {
+    md.push('## Examples')
+    examples.forEach(e => e.text.forEach(t => md.push(t.text)))
+  }
+
+  return md.join('\n')
+}

docs/frontend/composables/useConvertSecToMin.md

@@ -0,0 +1,18 @@
+# useConvertSecToMin
+Converts a duration in seconds to a formatted string representation in minutes and seconds.
+## Parameters
+| Name | Description |
+|------|-------------|
+|secs|The duration in seconds to convert.|
+## Returns
+A formatted string representing the duration in minutes and seconds.
+```
+(secs: number) => string
+```
+## Examples
+```ts
+useConvertSecToMin(135) // 2m 15s
+
+useConvertSecToMin(120) // 2m
+
+```

docs/frontend/composables/useDarkToggle.md

@@ -0,0 +1,16 @@
+# useDarkToggle
+Toggles between light and dark modes.
+## Returns
+An object with `isDark` (current mode) and `toggle` (toggle function).
+```
+() => { isDark: WritableComputedRef<boolean>; toggle: (value?: boolean) => boolean; }
+```
+## Examples
+```ts
+const {isDark, toggle} = useDark()
+
+isDark.value // false
+toggle()
+isDark.value // true
+
+```

docs/frontend/composables/useDateFormat.md

@@ -0,0 +1,18 @@
+# useDateFormat
+Format a date-like object into a predefined or custom format.
+## Parameters
+| Name | Description |
+|------|-------------|
+|date|The date-like object to format.|
+|format|The date format, either a predefined format ('DD/MM/YYYY') or a custom format string.|
+## Returns
+The formatted date as a string.
+```
+(date: DateLike, format: "DD/MM/YYYY" | Omit<string, "DD/MM/YYYY">) => string
+```
+## Examples
+```ts
+useDateFormat(new Date(), 'DD/MM/YYYY') // 22/09/2023
+
+useDateFormat(new Date(), 'dddd DD/MM') // Friday 22/09
+```

docs/frontend/composables/useDocTitle.md

@@ -0,0 +1,20 @@
+# useDocTitle
+Set the document's title with an optional prefix.
+## Parameters
+| Name | Description |
+|------|-------------|
+|title|The title to set.|
+|prefix|An optional prefix to prepend to the title.|
+## Returns
+
+```
+(title: string, prefix?: string) => void
+```
+## Examples
+```ts
+useDocTitle('New Title')
+document.title // DefaultPrefix New Title
+
+useDocTitle('New Title', 'MyPrefix')
+document.title // MyPrefix New Title
+```

docs/frontend/composables/useDriver.md

@@ -0,0 +1,14 @@
+# useDriver
+Provides access to the Driver.js instance and configuration for guided tours.
+## Returns
+An object containing the Driver.js instance and a function to set its configuration.
+```
+() => { driver: any; setConfig: (config: Omit<Config, "stagePadding" | "stageRadius">) => void; }
+```
+## Examples
+```ts
+const {driver, setConfig} = useDriver()
+
+setConfig({})
+driver.value.doSomething()
+```

docs/frontend/composables/useGet.md

@@ -0,0 +1,20 @@
+# useGet
+Execute a GET request and manage the response data, loading state, and errors.
+## Parameters
+| Name | Description |
+|------|-------------|
+|config|The configuration for the GET request.|
+## Returns
+An object containing the response data, loading state, error message, and an execution function.
+```
+(config: GetConfig) => { data: any; isFetching: any; error: any; execute: () => void; }
+```
+## Examples
+```ts
+const { data, isFetching, error, execute } = useGet({
+   url: '/api/example',
+   onSuccess(data){
+     //
+   }
+})
+```

docs/frontend/composables/useHash.md

@@ -0,0 +1,15 @@
+# useHash
+Generate a hash value for a given string.
+## Parameters
+| Name | Description |
+|------|-------------|
+|str|The input string to hash.|
+## Returns
+A hashed representation of the input string.
+```
+(str: string) => string
+```
+## Examples
+```ts
+useHash('somerandomstring') // 19viky0
+```

docs/frontend/composables/useLocale.md

@@ -0,0 +1,17 @@
+# useLocale
+Manage the application's locale and localization settings.
+## Returns
+An object containing available locales and the current locale.
+```
+() => { availableLocales: string[]; currentLocale: RemovableRef<string>; }
+```
+## Examples
+```ts
+const { currentLocale } = useLocale()
+
+currentLocale.value            // en
+document.documentElement.lang  // en
+
+currentLocale.value = 'de'
+document.documentElement.lang  // de
+```

docs/frontend/composables/usePost.md

@@ -0,0 +1,21 @@
+# usePost
+Execute a POST request and manage the response data, loading state, and errors.
+## Parameters
+| Name | Description |
+|------|-------------|
+|config|The configuration for the POST request.|
+## Returns
+An object containing the response data, loading state, error message, and an execution function.
+```
+<T>(config: PostConfig<T>) => { data: any; isFetching: any; error: any; execute: (body?: unknown) => void; }
+```
+## Examples
+```ts
+const { data, isFetching, error, execute } = useGet({
+   url: '/api/example',
+   body: { filePath: '/tmp/some.mp3' },
+   onSuccess(data){
+     //
+    }
+})
+```

docs/frontend/composables/useRandomColor.md

@@ -0,0 +1,11 @@
+# useRandomColor
+Generate a random RGBA color string with 50% opacity.
+## Returns
+A random RGBA color string in the format "rgba(r, g, b, 0.5)".
+```
+() => string
+```
+## Examples
+```ts
+useRandomColor() // rgba(123, 203, 78, 0.5)
+```

package.json

@@ -54,6 +54,7 @@
     "jsdom": "^22.1.0",
     "orval": "^6.17.0",
     "taze": "^0.11.2",
+    "tsdoc-markdown": "^0.1.0",
     "typescript": "^5.1.3",
     "unocss": "^0.55.7",
     "unplugin-auto-import": "^0.16.6",

src/frontend/components/SettingsGeneral.vue

@@ -4,7 +4,7 @@ import { LangMap, SUPPORT_FILE_TYPES } from '../includes/constants'
 
 const { t } = useI18n()
 
-const { currentLocal } = useLocale()
+const { currentLocale } = useLocale()
 const localOpts = Object.entries(LangMap).map(([key, value]) => ({ label: value, value: key }))
 
 const saveSettings = useLocalStorage('save-settings', { fileType: 'mp3', shouldAsk: true })
@@ -23,7 +23,7 @@ const saveSettings = useLocalStorage('save-settings', { fileType: 'mp3', shouldA
         <h3>{{ t('settings.general.language') }}</h3>
 
         <BaseSelect
-          v-model="currentLocal"
+          v-model="currentLocale"
           :options="localOpts"
           class="w-200px"
         />

src/frontend/composables/useConvertSecToMin.ts

@@ -1,8 +1,16 @@
 /**
  * Converts a duration in seconds to a formatted string representation in minutes and seconds.
  *
- * @param secs - The duration in seconds to convert.
- * @returns A formatted string representing the duration in minutes and seconds,
+ * @param secs The duration in seconds to convert.
+ * @returns A formatted string representing the duration in minutes and seconds.
+ *
+ * @example
+ * ```ts
+ * useConvertSecToMin(135) // 2m 15s
+ *
+ * useConvertSecToMin(120) // 2m
+ *
+ * ```
  */
 export function useConvertSecToMin(secs: number) {
   const _secs = Math.floor(secs)

src/frontend/composables/useDarkToggle.ts

@@ -4,6 +4,16 @@ import { useDark, useToggle } from '@vueuse/core'
  * Toggles between light and dark modes.
  *
  * @returns An object with `isDark` (current mode) and `toggle` (toggle function).
+ *
+ * @example
+ * ```ts
+ * const {isDark, toggle} = useDark()
+ *
+ * isDark.value // false
+ * toggle()
+ * isDark.value // true
+ *
+ * ```
  */
 export function useDarkToggle() {
   const isDark = useDark()