From f54d23f574dd169769f1f9d62e711a81c161185c Mon Sep 17 00:00:00 2001
From: Matt <cuffaro.matt@gmail.com>
Date: Wed, 17 Apr 2024 09:03:21 -0400
Subject: [PATCH] Adding Xdoc pattern to the template.

---
 src/AlgebraicTemplate.jl |  6 +++-
 src/Xdoc.jl              | 60 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 src/Xdoc.jl

diff --git a/src/AlgebraicTemplate.jl b/src/AlgebraicTemplate.jl
index e86b143..efccb7b 100644
--- a/src/AlgebraicTemplate.jl
+++ b/src/AlgebraicTemplate.jl
@@ -1,4 +1,4 @@
-""" Some description of ths package
+""" Some description of this package
 """
 module AlgebraicTemplate
 
@@ -6,6 +6,10 @@ export hello
 
 using Catlab
 
+# refer to this module for self-documenting functions
+include("Xdoc.jl")
+
+
 """ hello(name::String)
 
 Returns the string "Hello, <name>!" where `<name>` is replaced with the provided parameter
diff --git a/src/Xdoc.jl b/src/Xdoc.jl
new file mode 100644
index 0000000..3bb9338
--- /dev/null
+++ b/src/Xdoc.jl
@@ -0,0 +1,60 @@
+module Xdoc
+
+export @xdoc
+
+using Markdown
+
+function create_xdoc_expr(t)
+  name, source, desc, variable, expr = t
+  Base.remove_linenums!(expr)
+
+  exprdef = sprint.(Base.show_unquoted, expr.args)
+  exprdef = join(map(exprdef) do line; "    $line
+                 " end, "\n")
+
+  docstring = Markdown.parse("""
+
+  # $name 
+  
+  [Source]($source)
+
+  $desc
+
+  ## Model
+  
+  $exprdef
+
+  """)
+  quote
+    export $variable
+    $variable = $expr
+    @doc $docstring $variable
+  end
+end
+
+""" xdoc pattern
+
+It is generally useful to have ready-at-hand definition of a model, however a natural way of retrieving the definition is by calling the model in the REPL. While human-readable modeling is a design principle in AlgebraicJulia, an expression in the REPL may return information not necessary for a quick overview. Moreover, it should be available through Julia's documentation system.
+
+Decapodes.jl and GATlab.jl both implement a way to specify the documentation for a model at the time of defining it. For GATlab.jl, this is done without the need of a new macro. For Decapodes.jl, we use a `@docapode` macro to specify decapode expressions for models along with their sources, a description about them, and the variable that the model will be bound to.
+
+The "xdoc" pattern mimics the @docapode macro, set with the variable "x" for whichever modeling this package be intended. We define it here for your convenience.
+
+"""
+macro xdoc(name, source, desc, variable, expr)
+  create_xdoc_expr((name, source, desc, variable, expr)) |> esc
+end
+
+@xdoc("Sample Expression"
+,"https://github.com/AlgebraicJulia"
+,"A sample expression created with an 'Xdoc' pattern. This allows you to bind an expression to a variable while also defining it within its documentation."
+,sample_expr
+,begin
+  foo = 1
+  bar = 2
+
+  foobar = foo + bar
+end)
+  
+
+end