chore(gui-v2): add comments to `useApi`

packages/nc-gui-v2/composables/useApi/index.ts

@@ -14,6 +14,7 @@ interface UseApiReturn<D = any, R = any> {
   onResponse: EventHook<AxiosResponse<D, R>>['on']
 }
 
+/** {@link Api} options */
 interface CreateApiOptions {
   baseURL?: string
 }
@@ -27,10 +28,27 @@ export function createApiInstance<SecurityDataType = any>(options: CreateApiOpti
 }
 
 interface UseApiProps<D = any> {
+  /** additional axios config for requests */
   axiosConfig?: MaybeRef<AxiosRequestConfig<D>>
+  /** {@link Api} options */
   apiOptions?: CreateApiOptions
 }
 
+/**
+ * Api composable that provides loading, error and response refs, as well as event hooks for error and response.
+ *
+ * You can use this composable to generate a fresh api instance with its own loading and error refs.
+ *
+ * Any request called by useApi will be pushed into the global requests state and which toggles the global loading state.
+ *
+ * @example
+ * ```js
+ * const { api, isLoading, error, response, onError, onResponse } = useApi()
+ *
+ * const onSignIn = async () => {
+ *   const { token } = await api.auth.signIn(form)
+ * }
+ */
 export function useApi<Data = any, RequestConfig = any>(props: UseApiProps<Data> = {}): UseApiReturn<Data, RequestConfig> {
   const state = useGlobal()
 

packages/nc-gui-v2/composables/useGlobal/index.ts

@@ -2,13 +2,15 @@ import { useGlobalState } from './state'
 import { useGlobalActions } from './actions'
 import type { UseGlobalReturn } from './types'
 import { useGlobalGetters } from './getters'
-import { toRefs, useNuxtApp, watch } from '#imports'
+import { useNuxtApp, watch } from '#imports'
 
 /**
  * Global state is injected by {@link import('~/plugins/state') state} plugin into our nuxt app (available as `$state`).
- * Manual initialization is unnecessary and should be avoided.
+ * You can still call `useGlobal` to receive the `$state` object and access the global state.
+ * If it's not available yet, a new global state object is created and injected into the nuxt app.
  *
- * The state is stored in {@link WindowLocalStorage localStorage}, so it will be available even if the user closes the browser tab.
+ * Part of the state is stored in {@link WindowLocalStorage localStorage}, so it will be available even if the user closes the browser tab.
+ * Check the {@link StoredState StoredState} type for more information.
  *
  * @example
  * ```js
@@ -19,6 +21,18 @@ import { toRefs, useNuxtApp, watch } from '#imports'
  * const token = $state.token.value
  * const user = $state.user.value
  * ```
+ *
+ * @example
+ * ```js
+ * import { useGlobal } from '#imports'
+ *
+ * const globalState = useGlobal()
+ *
+ * cont token = globalState.token.value
+ * const user = globalState.user.value
+ *
+ * console.log(state.isLoading.value) // isLoading = true if any api request is still running
+ * ```
  */
 export const useGlobal = (): UseGlobalReturn => {
   const { $state, provide } = useNuxtApp()