From c12422278ac1fbfa41f97c6088e1d3fef21fd606 Mon Sep 17 00:00:00 2001
From: "Thomas A. Christensen II" <25492070+MillironX@users.noreply.github.com>
Date: Tue, 23 Nov 2021 13:59:27 -0600
Subject: [PATCH] Add documentation for cow the main function works

Signed-off-by: Thomas A. Christensen II <25492070+MillironX@users.noreply.github.com>
---
 docs/src/index.md | 10 ++++++---
 src/Cowsay.jl     | 55 +++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 60 insertions(+), 5 deletions(-)

diff --git a/docs/src/index.md b/docs/src/index.md
index 7ab6fb8..04a6642 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -2,9 +2,13 @@
 CurrentModule = Cowsay
 ```
 
-# cowsay
+# Cowsay.jl
 
-Documentation for [cowsay](https://github.com/MillironX/cowsay.jl).
+A Julia package that lets you use
+[cowsay](https://en.wikipedia.org/wiki/Cowsay) in your Julia programs!
 
-```@index
+## Usage
+
+```@docs
+Cowsay.cowsay
 ```
diff --git a/src/Cowsay.jl b/src/Cowsay.jl
index 1811852..5760405 100644
--- a/src/Cowsay.jl
+++ b/src/Cowsay.jl
@@ -16,9 +16,60 @@ include("cows/vader.cow.jl")
 include("cows/www.cow.jl")
 
 """
-    cowsay(message::AbstractString)
+    cowsay(message::AbstractString; kwargs...)
 
-Prints a cow saying `message` as unwrapped text.
+Print an ASCII picture of a cow saying `message`
+
+# Arguments
+- `message::AbstractString`: Tell the cow what to say
+
+# Keywords
+- `cow=default`: Specify a particular function handle to print the ASCII art. See below for
+    more details on what constitutes a valid function handle.
+- `eyes::AbstractString="oo"`: A two-character string to be drawn in for the eyes. Not all
+    cowfiles support this, though.
+- `tongue::AbstractString="  "`: A two-character string to be drawn in for the tongue. Not
+    all cowfiles support this.
+
+---
+
+# Making a cow function
+
+The original cowsay used Perl scripts (called 'cowfiles') to allow for creating more ASCII
+cow art. Cowsay.jl uses Julia functions, instead. In order to be usable by `Cowsay.cowsay`,
+a cow function **must**
+
+1. Take the correct arguments
+
+    The function must take three (3)
+    [keyword arguments](https://docs.julialang.org/en/v1/manual/functions/#Keyword-Arguments)
+    of the form
+
+    - `eyes::AbstractString="oo"`
+    - `tongue::AbstractString="  "`
+    - `thoughts::AbstractString="\\"`
+
+    When drawing the cow artwork, you may then use the variables `eyes` in place of the
+    eyes, `tongue` in place of the tongue, and `thoughts` in place of the speech ballon
+    trail. Use of these variables in constructing the cow is optional (but makes the use of
+    your cow function far more fun), but all three arguments must be present in the
+    signature, regardless.
+
+2. Return a string
+
+    The cow artwork must be returned from the function as a string. This is distinctly
+    different from how the original cowsay modified the `\$the_cow` variable.
+
+## Helpful hints for making cow functions
+
+1. Include one function per file, with the extension `.cow.jl`
+2. Do not indent within a `.cow.jl` file to better see the artwork
+3. Make use of string literals (`\"""`) and string interpolation (`\$`) to build the cow
+    art
+4. Be sure to escape backslashes (`\\`) and dollar signs (`\$`) within your artwork
+5. Split the `eyes` variable to get individual left- and right-eye when creating large cow
+    functions
+6. Have fun!
 """
 function cowsay(message::AbstractString; cow=default, eyes="oo", tongue="  ")
     messagelines = split(message, "\n")