Update comments and docstrings

Makefile

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2024 James Cherti | https://www.jamescherti.com/contact/
+# Copyright (C) 2023-2024 James Cherti | https://www.jamescherti.com/contact/
 # URL: https://github.com/jamescherti/dir-config.el
 #
 # This file is free software; you can redistribute it and/or modify

README.md

@@ -39,12 +39,12 @@ To install the `dir-config` using `straight.el`:
 ```
 
 Note:
-- The dir-config file names can be customized by modifying: ```(setq dir-config-file-names '(".project-config.el" ".dir-config.el"))```. With this configuration, Emacs will search for the `.project-config.el` file first, and if it is not found, it will then search for the `.dir-config.el` file'.
+- The dir-config file names can be customized by modifying the dir-config-file-names variable. For instance: ```(setq dir-config-file-names '(".project-config.el" ".dir-config.el"))``` will make `dir-config` search for the `.project-config.el` file first, and if it is not found, it will then search for the `.dir-config.el` file'.
 - You can set `(setq dir-config-verbose t)` and `(setq dir-config-debug t)` to increase the verbosity of messages each time a file is loaded while `global-dir-config-mode` is active.
 
 ## Usage
 
-Assuming that the `dir-config-dir` package has been configured to allow loading configuration files from specific directories, such as `~/src`, by setting the `dir-config-allowed-directories` variable:
+Assuming that the `dir-config` package has been configured to allow loading configuration files from specific directories, such as `~/src`, by setting the `dir-config-allowed-directories` variable:
 ``` emacs-lisp
 (setq dir-config-allowed-directories '("~/src" "~/projects"))
 ```
@@ -68,7 +68,7 @@ It is recommended to always begin your `.dir-config.el` files with the following
 ;;; .dir-config.el --- Directory config -*- no-byte-compile: t; lexical-binding: t; -*-
 ```
 
-The `dir-config-dir` package allows for automatic application of specific configurations based on the directory of the files being accessed, enhancing the flexibility and customization of the Emacs environment.
+The `dir-config` package allows for automatic application of specific configurations based on the directory of the files being accessed, enhancing the flexibility and customization of the Emacs environment.
 
 ## Frequently Asked Questions
 
@@ -78,13 +78,13 @@ Here is the difference between using `.dir-locals.el` (built-in) and the `.dir-c
 
 - `.dir-locals.el` (built-in):
   - Primarily used for setting per-directory local variables.
-  - The syntax of `.dir-locals.el` relies heavily on nested lists and alist structures. This can quickly become difficult to read and maintain, especially for more complex configurations.
+  - The syntax of `.dir-locals.el` relies heavily on nested lists and alist structures. This can quickly become **difficult to read and maintain**, especially for more complex configurations.
   - The configuration in `dir-locals.el` is inherently static unless dynamic behavior is explicitly added using `eval`.
 
 - `.dir-config.el` (The `dir-config` package):
   - Provides more extensive capabilities by loading and evaluating Emacs Lisp code for tasks such as environment configuration, keybindings, and other complex setup processes.
   - Better suited for more complex, project-specific setups where additional customization and dynamic behavior are required.
-  - `.dir-config.el` files are easier to maintain, as they use standard Emacs Lisp code instead of nested alists.
+  - `.dir-config.el` files are easier to maintain, as they use standard Elisp code instead of nested alists.
 
 If the user’s needs primarily involve configuring Emacs variables, the built-in `.dir-locals.el` is sufficient. For more advanced, project-specific configurations that include code execution and comprehensive environment management, `.dir-config.el` files offer more flexibility and control.
 

dir-config.el

@@ -71,21 +71,22 @@
 (defcustom dir-config-file-names '(".dir-config.el")
   "List of filenames for directory configuration files.
 
-The dir-config package will search for these files in the directory hierarchy
-of the current buffer, starting from the buffer's directory and moving upward
-through parent directories. The first existing file found will be used for
-configuration.
+The `global-dir-config-mode' mode will search for these files in the directory
+hierarchy of the current buffer, starting from the buffer's directory and moving
+upward through parent directories. The first existing file found will be used
+for configuration.
 
-For example, if this list contains .dir-config.el and .project-config.el, Emacs
-will search for the .dir-config.el file first. If not found, it will then search
-for the .project-config.el fil."
+For example, if this list contains .dir-config.el and .project-config.el,
+`global-dir-config-mode' will search for the .dir-config.el file first. If not
+found, it will then search for the .project-config.el fil."
   :type '(repeat string)
   :group 'dir-config)
 
 (defcustom dir-config-verbose nil
-  "If non-nil, enable verbose logging for `dir-config' operations.
-When enabled, detailed logs will be produced when a dir-config file is loaded or
-ignored. This is useful for tracking the flow of dir-config loading."
+  "If non-nil, enable verbose logging for dir-config operations.
+When enabled, detailed logs will be produced when a dir-config file (e.g.,
+'.dir-config.el') is loaded or ignored. This is useful for tracking the flow of
+dir-config loading."
   :type 'boolean
   :group 'dir-config)
 
@@ -102,7 +103,9 @@ This option is useful for diagnosing and troubleshooting complex issues."
   :group 'dir-config)
 
 (defcustom dir-config-allowed-directories '()
-  "List of directory names where dir-config files are allowed."
+  "List of directory names where dir-config files are allowed.
+Both the dir-config file (e.g., '.dir-config.el') and the buffer path must be
+under these directories, not just the dir-config file."
   :type '(repeat directory)
   :group 'dir-config)
 
@@ -134,7 +137,7 @@ Returns t if all files are within an allowed directory, nil otherwise."
    allowed-directories))
 
 (defun dir-config-get-dir ()
-  "Return the directory of the currently loaded dir-config, or nil if none."
+  "Return the directory of the loaded dir-config file, or nil if none."
   (when (bound-and-true-p dir-config--file)
     (file-name-directory dir-config--file)))
 
@@ -153,18 +156,16 @@ Returns t if all files are within an allowed directory, nil otherwise."
 
 (defun dir-config--buffer-cwd ()
   "Return the directory associated with the current buffer.
-
 Returns:
 - The directory path if the buffer is in `dired-mode', or
 - The directory of the file if the buffer is visiting a file, or
 - nil if neither condition is met."
   (let ((file-name (buffer-file-name (buffer-base-buffer))))
-    (cond
-     ((derived-mode-p 'dired-mode)
-      (dired-current-directory))
+    (cond ((derived-mode-p 'dired-mode)
+           (dired-current-directory))
 
-     (file-name
-      (file-name-directory file-name)))))
+          (file-name
+           (file-name-directory file-name)))))
 
 (defun dir-config--find-dominating-file (file-names start-dir)
   "Locate the first available file from FILE-NAMES in the directory hierarchy.
@@ -212,7 +213,7 @@ from the closest parent directory of the buffer."
           (if (not dir-config-file)
               (when dir-config-debug
                 (dir-config--message (concat
-                                      "[DEBUG] %s: one of the dir-config "
+                                      "[DEBUG] %s: None of the dir-config "
                                       "files %s were found for the '%s' "
                                       "buffer (major-mode: %s)")
                                      (buffer-name)

tests/test-dir-config.el

@@ -1,6 +1,6 @@
 ;;; test-dir-config.el --- Test dir-config -*- lexical-binding: t; -*-
 
-;; Copyright (C) 2024 James Cherti | https://www.jamescherti.com/contact/
+;; Copyright (C) 2023-2024 James Cherti | https://www.jamescherti.com/contact/
 
 ;; Author: James Cherti
 ;; Version: 1.0.0