Revise comments with better formatting

flake.nix

@@ -1,17 +1,29 @@
+/*
+INFO:
+`flake.lock` file in the current directory captures the version of dependencies and locks them
+This is important for reproducibility in deploying Nix installations throughout multiple hosts
+
+To learn about flakes and flake schema, refer to https://nixos.wiki/wiki/Flakes
+
+NOTE:
+Prefer `nix <commmand>` command rather than `nix-<something>` commmands if flake setup exists
+*/
 {
-  description = "Foo the Frog's NixOS and Home Manager configurations";
+  description = "Foo the Frog's NixOS and Home Manager configuration flake";
 
+  # Specify dependencies in `inputs` attribute
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
 
     home-manager = {
-      url = "github:nix-community/home-manager";
       /*
-      Here,
-      `inputs.nixpkgs` of home-manager is consistent with `input.nixpkgs` of the flake
+      INFO:
+      `inputs.nixpkgs` attribute for Home Manager is consistent with `input.nixpkgs` of this flake
       This avoids issues caused by different versions of packages
+
+      `follows` is a special keyword used for inheritance in Nix expressions
       */
-      inputs.nixpkgs.follows = "nixpkgs"; # The `follows` keyword is used for inheritance
+      inputs.nixpkgs.follows = "nixpkgs";
     };
   };
 
@@ -26,6 +38,7 @@
         modules = [
           ./hosts/foobar/systemwide.nix
 
+          # Deploy Home Manager configuration automatically when running `nixos-switch rebuild` command
           home-manager.nixosModules.home-manager
           {
             home-manager = {

hosts/foobar/systemwide.nix

@@ -17,14 +17,14 @@
   nix.settings.experimental-features = ["nix-command" "flakes"];
 
   /*
-  Here,
-  The value dictates the NixOS release version that was installed initially
-  It's important to determine the default system state for that NixOS release
-  It's perfectly OK and recommended to leave it unchanged
+  INFO:
+  The value of `stateVersion` is the NixOS release version installed initially for this system
+  This is required for determining the default system state for that NixOS release
+  
 
-  However,
-  If it should be changed, read the man page for `configuration.nix` beforehand
-  Ref: https://nixos.org/nixos/options.html
+  NOTE:
+  It is perfectly OK and recommended to leave it unchanged
+  But if it has to be changed, read about it in the man page for `configuration.nix` beforehand
   */
   system.stateVersion = "23.11";
 }

hosts/foobar/userspace.nix

@@ -6,10 +6,12 @@
   ];
 
   /*
-  Here,
-  The value is the Home Manager release version that was installed initially
-  This helps avoid breakage when a new Home Manager release introduces backwards incompatible changes
-  It's perfectly OK and recommended to leave it unchanged even after updating Home Manager
+  INFO:
+  The value of `home.stateVersion` is the Home Manager release version installed initially for this system
+  This is required to help avoid breakage when a new Home Manager release introduces backwards incompatible changes
+  
+  NOTE:
+  It is perfectly OK and recommended to leave it unchanged even after a Home Manager update
   */
   home.stateVersion = "24.05";
 }

modules/applications/extra/steam.nix

@@ -6,10 +6,12 @@
       gamescopeSession.enable = true;
     };
 
-    gamemode.enable = true; # Temporary optimizations applies to the OS in-game, improving performance
+    # INFO: It applies temporary optimizations applies to the OS in-game, improving performance
+    gamemode.enable = true;
   };
 
   /*
+  NOTE:
   Prepend `mangohud` in launch options within Steam client's General settings as `mangohud %command%`
   to access its capabilities in-game. Same goes for other such programs.
   */

modules/applications/packages.nix

@@ -3,9 +3,9 @@
   nixpkgs.config.allowUnfree = true;
 
   # List packages installed in system profile
+  # NOTE: To search, run: `nix search nixpkgs <package>` command
   environment.systemPackages = with pkgs; [
-    # To search, run: `nix search <package>` command
-    #ToDo: Add small descriptions for each packages as comments with basic refactoring
+    # TODO: Add a small comment description for each package in the list
     macchina
     helix
 

modules/applications/programs.nix

@@ -13,7 +13,7 @@
       };
     };
 
-    # Ref: https://nixos.wiki/wiki/Git
+    # INFO: https://nixos.wiki/wiki/Git
     git = {
       enable = true;
       lfs.enable = true;

modules/applications/services.nix

@@ -1,11 +1,11 @@
 _: {
   services = {
     # Auto mount USB removable devices
-    # Ref: https://nixos.wiki/wiki/PCManFM#USB_Automounting
+    # INFO: https://nixos.wiki/wiki/PCManFM#USB_Automounting
     udisks2.enable = true;
     devmon.enable = true;
 
-    # Necessary for GnuPG to work correctly
+    # NOTE: Necessary for GnuPG to work correctly
     pcscd.enable = true;
   };
 }

modules/bootloader.nix

@@ -3,17 +3,17 @@
     # Limit the number of generations that show up at boot entries
     configurationLimit = lib.mkDefault 5;
 
-    # Enable editing the kernel command-line before boot
-    editor = false; # is enabled (by default) unless set to false
     /*
-    Here,
-    It is recommended to set `editor` to false
-    Otherwise it allows to gain root access by passing `init=/bin/sh` as kernel parameter
+    WARN:
+    Enabling `editor` attribute allows passing `init=/bin/sh` as kernel parameter to gain root access
+    Considering the security risk, disabling this is recommended
     */
+    editor = false;
 
-    # Set the highest resolution for `sytemd-boot`'s console
+    # Set the highest resolution available for boot console
     consoleMode = lib.mkDefault "max";
   };
 
+  # Enable to allow the bootloader to modify EFI variables
   boot.loader.efi.canTouchEfiVariables = true;
 }

modules/fonts.nix

@@ -1,6 +1,5 @@
 {pkgs, ...}: {
   fonts = {
-    # use fonts specified by user rather than default ones
     enableDefaultPackages = false;
     fontDir.enable = true;
 
@@ -11,7 +10,8 @@
       noto-fonts-emoji
       noto-fonts-extra
 
-      # Ref: https://github.com/NixOS/nixpkgs/blob/nixos-24.05/pkgs/data/fonts/nerdfonts/shas.nix
+
+      # INFO: https://github.com/NixOS/nixpkgs/blob/nixos-24.05/pkgs/data/fonts/nerdfonts/shas.nix
       (nerdfonts.override {
         fonts = [
           "NerdFontsSymbolsOnly"
@@ -23,11 +23,7 @@
       })
     ];
 
-    /*
-    Here,
-    Noto Color Emoji is explicity specified everywhere
-    This is to override DejaVu's B&W emojis that might show up sometimes
-    */
+    # NOTE: Noto Color Emoji is explicitly specified to potentially override emojis from other fonts
     fontconfig.defaultFonts = {
       serif = ["Noto Serif" "Noto Serif CJK JP" "Noto Color Emoji"];
       sansSerif = ["Noto Sans" "Noto Sans CJK JP" "Noto Color Emoji"];

modules/graphics/nvidia.nix

@@ -16,12 +16,12 @@
     modesetting.enable = true;
 
     powerManagement = {
-      # Currently experimental
+      # NOTE: Currently experimental
       enable = false;
       finegrained = false;
     };
 
-    nvidiaSettings = true; # For `nvidia-settings` command
+    nvidiaSettings = true; # NOTE: It enables the `nvidia-settings` command
     open = false;
     nvidiaPersistenced = true;
 

modules/internet.nix

@@ -1,13 +1,13 @@
-_: {
+https://nixos.wiki/wiki/Wpa_supplicant_: {
   networking = {
     useDHCP = false;
-    # ToDo: Autogenerate hostname based on the respective host
+    # TODO: Implement functionality for generating hostname automatically based on the current host
     hostName = "";
 
     networkmanager = {
       enable = true;
-      # Enable wireless support via wpa_supplicant
-      # Ref: https://nixos.wiki/wiki/Wpa_supplicant
+      # Enable wireless support via `wpa_supplicant`
+      # INFO: https://nixos.wiki/wiki/Wpa_supplicant
       # wireless.enable = true;
 
       # Configure network proxy if necessary

modules/peripherals/audio.nix

@@ -1,14 +1,16 @@
 {pkgs, ...}: {
   environment.systemPackages = with pkgs; [
-    pulseaudio # provides `pactl`, which is required by some apps (e.g. sonic-pi)
+    pulseaudio # NOTE: The package comes with `pactl`, which is required by some apps (e.g. sonic-pi)
   ];
 
   /*
+  INFO:
   PipeWire is a new low-level multimedia framework
   It aims to offer capture and playback for both audio and video with minimal latency
   It has support for PulseAudio-, JACK-, ALSA- and GStreamer-based applications
   PipeWire has a great bluetooth support, it can be a good alternative to PulseAudio
-  Ref: https://nixos.wiki/wiki/PipeWire
+  
+  https://nixos.wiki/wiki/PipeWire
   */
   services.pipewire = {
     enable = true;
@@ -23,10 +25,10 @@
     alsa.support32Bit = true;
   };
 
-  # `rtkit` is optional but recommended
+  # NOTE: `rtkit` is optional but enabling it is recommended
   security.rtkit.enable = true;
-  # Remove `sound.enable` or turn it off if it was set previously as it may conflict with `pipewire`
+
+  # NOTE: Both of these may conflict with `pipewire` so disabling them is recommended
   sound.enable = false;
-  # Disable `pulseaudio` as it can conflict with `pipewire`
   hardware.pulseaudio.enable = false;
 }

modules/peripherals/bluetooth.nix

@@ -7,6 +7,6 @@ _: {
     hsphfpd.enable = false; # is not explictly required if PulseAudio is enabled
   };
 
-  # Enable `blueman` a full featured bluetooth manager and with GUI using the `blueman-manager` command
+  # Enable `blueman` for a full featured bluetooth manager including a GUI
   services.blueman.enable = true;
 }

modules/users/foo/home-depot/programs.nix

@@ -1,4 +1,4 @@
-# ToDo: Split `./programs.nix` into files under `./programs` for program-specific configurations respectively
+# TODO: Split `./programs.nix` into files under `./programs` directory for program-specific configurations
 {pkgs, ...}: {
   home-manager.users.foo = {
     gtk = {

modules/users/foo/user.nix

@@ -1,7 +1,7 @@
 {pkgs, ...}: {
   /*
-  Removing a user does not remove their profile
-  Ref: https://github.com/NixOS/nix/issues/4419>
+  NOTE: Removing a user does not remove their profile
+  INFO: https://github.com/NixOS/nix/issues/4419
   */
   users.users.foo = {
     description = "User named foo";
@@ -17,8 +17,12 @@
 
     # Set the groups this user will be associated with
     extraGroups = [
-      # to see available group(s) use `cut -d: -f1 /etc/group` command
-      "wheel" # to see member(s) of a particular group, use `getent group <group>` commmand
+      /*
+      NOTE:
+      To see available group(s) use `cut -d: -f1 /etc/group` command
+      To see member(s) of a particular group, use `getent group <group>` commmand
+      */
+      "wheel"
       "disk"
       "audio"
       "video"

modules/users/root.nix

@@ -5,7 +5,7 @@
     "System Operators love to use `GOD`, it's a whole male ego thing."
       - Cereal Killer, Hackers (1995)
     */
-    initialPassword = "GOD"; # to change this, use `passwd` command
+    initialPassword = "GOD"; # NOTE: Use `passwd` command to change this
     shell = pkgs.fish;
   };
 }