docs: update comments in sources

.npmrc

@@ -1,2 +1,4 @@
+# settings for Nuxt & pnpm
+# https://cuyl.github.io/pnpm.github.io/npmrc/
 shamefully-hoist=true
 strict-peer-dependencies=false

assets/css/open-props.css

@@ -2,14 +2,19 @@
   This will import Open Props CSS styles
   https://open-props.style/
 
-  NUXT_PUBLIC_IGNIS_OPENPROPS=true required to use this feature
+  NUXT_PUBLIC_IGNIS_OPENPROPS=true is required to use this feature
 */
 
 @import "open-props/normalize";
 @import "open-props/buttons";
 
+/* demo class - used in AppFeature component instance */
 .openprops-feature {
+
   /* https://open-props.style/#gradients */
   background: var(--gradient-18);
+
+  /* https://open-props.style/#colors */
   color: var(--gray-12);
+
 }

assets/css/tailwind.css

@@ -1,18 +1,31 @@
-/* This file is auto-imported when using Tailwind CSS */
-/* Read more at: */
-/* https://tailwindcss.com/docs/reusing-styles#extracting-classes-with-apply */
+/* 
+  This file is auto-imported when using Tailwind CSS
+
+  Use @apply if you don't want to define style for each element separately
+
+  Read more at:
+  https://tailwindcss.com/docs/reusing-styles#extracting-classes-with-apply
+  https://tailwindcss.com/docs/functions-and-directives#apply
+
+  Use correct @layer to keep your Tailwind CSS organized:
+  https://bloggie.io/@kinopyo/organize-your-css-in-the-tailwind-style-with-layer-directive
+
+  And most importantly: THINK TWICE before using this approach!
+*/
 
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
 
 @layer base {
 
-    /* Tailwind CSS classes might be auto-applied to all respective elements like this. */
-    /* However, I recommend NOT to use it like that, because this obsfucates code logic */
-    /* and makes maintaing harder (even you should soon forgot styles are defined here) */
+    /* 
+      Tailwind CSS classes might be auto-applied to all respective elements like this.
+      However, I recommend NOT to use it like that, because this obsfucates code logic
+      and makes maintaing harder (even you should soon forgot styles are defined here)
+    */
 
-    /* For setting "body" tag attributes, it is better to use useHead() composable - @see `app.vue`*/
+    /* NOTE: For setting "body" tag attributes, it is better to use useHead() composable - @see `app.vue`*/
     /*
     body {
         @apply bg-slate-900;
@@ -23,9 +36,11 @@
 
 @layer components {
 
-    /* Following classes are available to use throughout the app as shorthands.  */
-    /* Although still discouraged by Tailwind CSS authors, this usage makes more */
-    /* sense, because the class name is visible and trackable in SFC templates.  */
+    /* 
+      Following classes are available to use throughout the app as shorthands.
+      Although still discouraged by Tailwind CSS authors, this usage makes more
+      sense, because the class name is visible and trackable in SFC templates.
+    */
 
     .link {
         @apply my-2 text-amber-400 hover:text-amber-200;

components/AppFeature.vue

@@ -10,38 +10,53 @@
     https://vuejs.org/api/sfc-script-setup.html
 
     For usage go to `/pages/index.vue`
+
+    {{ text }}
+     - "double mustache" syntax is used to display JS expression inside HTML template
+     - notice you can call props directly in template section
+
+    Icon
+     - icons are provided by "nuxt-icon" module
+     - module is auto-imported via "@nuxt/ui"
+     - NUXT_PUBLIC_IGNIS_UI=nuxt-ui is required to use this feature
 -->
 
 <template>
   <div class="m-1 px-2 py-1 border border-amber-300 font-bold text-lg text-feature hover:bg-slate-700">
-    <!-- "double mustache" syntax to display JS expression inside HTML template -->
-    <!-- notice you can call props directly in template section -->
     {{ text }}
-    <!-- icons provided by "nuxt-icon" module auto-imported via "@nuxt/ui" -->
     <div v-if="showIcon" style="display: inline;">
       <Icon name="ic:sharp-add-reaction" style="color: yellow" />
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
-// defineProps() comming from Vue.js Composition API itself
-// https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits
-// this is how you pass variables inside components
-// required - value has to be provided, otherwise an error will occur
-// default - will have this value, unless overwritten by caller
+/**
+ * Macro `defineProps()` comes from Vue.js API
+ * (https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits).
+ * This is how to pass variables inside components in Vue.
+ * 
+ * `required` - value has to be provided, otherwise an error will occur
+ * 
+ * `default` - will have this value, unless overwritten by caller
+ */
 const props = defineProps({
   text: { type: String, required: true },
   optionalText: { type: String, default: 'default' },
 })
 
+/**
+ * `Icon` component can only be used if `@nuxt/ui` module is activated.
+ */
 const showIcon = useRuntimeConfig().public.ignis.ui === 'nuxt-ui'
 
-// in setup section, you have to adress properties like this
-// you cannot reach them directly unlike in template
+// In setup section, you have to adress properties like this.
+// You cannot reach them directly like in template.
+
+// Note special inline `eslint` flag because normally you shouldn't use build-in console directly
+// @see https://eslint.org/docs/latest/rules/no-console
+
 /* eslint "no-console" : "off" */
 log.debug(props.text)
 log.debug(props.optionalText)
-// note special inline eslint flag because normally you shouldn't use build-in console directly
-// see https://eslint.org/docs/latest/rules/no-console
 </script>

components/CurrentTime.vue

@@ -1,3 +1,12 @@
+<!--
+  The `NuxtTime` component of `nuxt-time` module is a way how to deal with SSR in Nuxt.
+  Because page on the server is rendered miliseconds before being re-rendered on client,
+  wild "hydration error mismatch" may appear from a difference between displayed times.
+
+  This special component gracefully deals with the issue:
+  https://github.com/nuxt/nuxt/discussions/23278#discussioncomment-7607298
+-->
+
 <template>
   <div>
     Current time by

composables/useTranslation.ts

@@ -1,3 +1,5 @@
+import lang from '@/assets/lang/en.json'
+
 /**
  * An adapter above `t` function from `i18n` module.
  * 
@@ -11,9 +13,6 @@
  * @param key identifier of text that should be displayed
  * @returns translated text from i18n sources
  */
-
-import lang from '@/assets/lang/en.json'
-
 export function useT(key: string): string {
   if (useRuntimeConfig().public.ignis.i18n) {
     // i18n available => just use it
@@ -31,6 +30,7 @@ export function useT(key: string): string {
   }
 }
 
+/** AI-generated helper to search a value for given key in JSON lang file. */
 function searchLang(key: string): unknown {
     const keys = key.split(".")
 

pages/index.vue

@@ -2,14 +2,20 @@
     https://nuxt.com/docs/guide/directory-structure/pages
 
     An example of Nuxt page.
-    Nuxt automaticaly provides routing and displays this page when user visits root URL.
+    Nuxt automaticaly provides routing and displays this page when user visits root URL or `/index`.
+
+    AppFeature
+     - an example usage of auto-imported Nuxt component declared in `/components` directory
+     - the text is (usually) being loaded localized via nuxtjs/i18n module
+     - features are being displayed conditionally according to current setting
+
+    NuxtLink
+     - special component for improved handling for HTML links (<a> tags)
 -->
 
 <template>
   <div>
     <div class="m-auto my-4 w-3/5 flex flex-col">
-      <!-- an example of Nuxt components declared in `/components` directory -->
-      <!-- the text is being loaded localized via nuxt/i18n module -->
       <AppFeature :text="useT('features.nuxt')" />
       <AppFeature :text="useT('features.security')" />
       <AppFeature :text="useT('features.image')" />

pages/second.vue

@@ -1,7 +1,10 @@
 <!--
     https://nuxt.com/docs/guide/directory-structure/pages
 
-    This page appears under `/second`
+    This page appears under URL `/second`
+
+    NuxtImg
+    - special component for displaying images with NuxtImage module
 -->
 
 <template>
@@ -10,7 +13,6 @@
       {{ useT("page2") }}
     </div>
     <div class="m-4 flex flex-col items-center">
-      <!-- special component for displaying images with NuxtImage -->
       <NuxtImg src="/unsplash.jpg" width="400" />
       <div class="text-xs">
         {{ useT("image") }}

utils/ignis-types.ts

@@ -1,2 +1,21 @@
+/**
+ * Available variants for UI libraries.
+ * 
+ * `nuxt-ui` - full https://ui.nuxt.com/ via `@nuxt/ui` connector module **[RECOMMENDED]**
+ * 
+ * `tailwind` - only https://tailwindcss.com/ via `@nuxtjs/tailwindcss` connector module
+ * 
+ * `off` - no UI library **[DEFAULT]**
+ */
 export type UIOptions = 'nuxt-ui' | 'tailwind' | 'off'
-export type DBOptions = 'neon' | 'supabase' | 'off'
+
+/**
+ * Available variants for Database connector.
+ * 
+ * `neon` - https://neon.tech/ via `nuxt-neon` connector module **[RECOMMENDED]**
+ *
+ * `supabase` - https://supabase.com/ via `@nuxtjs/supabase` connector module
+ * 
+ * `off` - no database module **[DEFAULT]**
+ */
+export type DBOptions = 'neon' | 'supabase' | 'off'