Standardize module READMEs

modules/feature/eval/README.org

@@ -1,17 +1,21 @@
-* :feature eval
+#+TITLE: :feature eval
 
-This module adds support for:
+This modules adds support for REPLs, build tasks and code evaluation.
 
-+ [[#repls][Defining, invoking & interacting with REPLs]],
-+ [[#build-tasks][Defining & invoking build tasks for projects and files]],
-+ and [[#code-evaluation][evaluating code or entire buffers, printing their output to a popup window]].
+* Table of Contents :TOC:
+- [[#install][Install]]
+- [[#usage][Usage]]
+- [[#configuration][Configuration]]
+  - [[#repls][REPLs]]
+  - [[#build-tasks][Build Tasks]]
+  - [[#code-evaluation][Code Evaluation]]
 
-** Install
+* Install
 This module has no external dependencies. However, specific languages may require additional setup.
 
 Check the README.org in that language's module for details.
 
-** Usage
+* Usage
 + *REPLs*
   Invoked via:
   + ~:repl~ (evil ex-command)
@@ -33,13 +37,15 @@ Check the README.org in that language's module for details.
   + ~M-x +eval/region-and-replace~
   + Evil users can use the ~gr~ operator to select and run a region.
 
-** Configuration
-*** REPLs
-REPLs have been defined for most of the languages DOOM supports (check its README.org to see if it does).
+* Configuration
+** REPLs
+REPLs are defined for most of the languages Doom supports (check its README.org to see if it does).
 
-Otherwise, you can define your own:
+Otherwise, you can define your own for a specified major-mode with the =:repl= setting.
 
-A REPL definition consists of two parts: an interactive command that opens (and returns) a REPL buffer and a ~:repl~ definition that maps a major-mode to said command:
+~(set! :repl MAJOR-MODE FUNCTION)~
+
+FUNCTION must return the repl buffer. Any window changes are ignored, then handed off to shackle (assuming shackle-mode is on) to display in a popup window.
 
 #+BEGIN_SRC emacs-lisp
 (defun +emacs-lisp/repl ()
@@ -54,8 +60,8 @@ A REPL definition consists of two parts: an interactive command that opens (and
 (set! :repl 'emacs-lisp-mode #'+emacs-lisp/repl)
 #+END_SRC
 
-*** Build Tasks
-A build task is little more than major-mode-local commands, comprised of an interactive command, an association with a major mode and an optional predicate function.
+** Build Tasks
+A build task is little more than a major-mode-local interactive command that performs a task, such as compiling the current project or running unit tests. A predicate function can be supplied to ensure a command is only available when it is appropriate.
 
 #+BEGIN_SRC emacs-lisp
 (defun +lua/run-love ()
@@ -83,7 +89,7 @@ A build task is little more than major-mode-local commands, comprised of an inte
 (set! :build 'generate-docs 'lua-mode #'+lua/generate-docs)
 #+END_SRC
 
-*** Code Evaluation
+** Code Evaluation
 Run regions or entire buffers with [[https://github.com/syohex/emacs-quickrun][Quickrun]]. Output will be sent to a popup window.
 
 Quickrun includes support for many languages, but occasionally, you'll find a language without support, such as [[https://crystal-lang.org/][Crystal]]. A "runner" can be defined like so: