Switch docs to autogenerated

make-docs.fnl

@@ -28,6 +28,24 @@
               (table.insert modules (section:sub index)))
             (table.insert fields section)))
         (when header (loop header))))
+
+    ;; Artificially insert the `arg` docs.
+    ;; This isn't present in the "Basic Functions" part of the manual, but is still useful to be included in the docs.
+    (let [arg-signature "<hr><h3><a name=\"pdf-arg\"><code>arg</code></a></h3>\n"
+          arg-description (-> html
+                              ;; The goal here is to extract the smallest string which:
+                              ;; 1) contains the string "global table called <code>arg</code>"
+                              ;; 2) ends with "\n<p>" (not inclusive)
+                              ;; 3) begins with "\n<p>" (not inclusive)
+
+                              ;; This match fufills 1 and 2
+                              (: :match "(.*global table called <code>arg</code>.-)\n<p>")
+                              ;; trust me, I tried everything.
+                              ;; The best way to do 3 is a non-greedy search in reverse
+                              (: :reverse)
+                              (: :match "(.-)>p<\n")
+                              (: :reverse))]
+      (table.insert fields (.. arg-signature arg-description)))
     (loop (stdlib:find "<hr><h3>.-\n"))
     (values modules fields last-update)))
 
@@ -107,7 +125,10 @@
         ;; fix spaces
         signature (signature:gsub " +" " ")
         signature (signature:gsub " +%)" ")")
-
+        signature-list (case (signature:match "^%((.-)%)$")
+                         call (doto (icollect [arg (call:gmatch "[^ ]+")]
+                                     arg)
+                                    (table.remove 1)))
         ;; <code> tags for optional args
         description (accumulate [description description _ arg (ipairs optional-args)]
                       (description:gsub (.. "<code>" arg "</code>")
@@ -122,7 +143,8 @@
     (values ?module
             key
             {:binding (signature:match "[^() ]+")
-             :metadata {:fnl/docstring description}})))
+             :metadata {:fnl/docstring description
+                        :fnl/arglist signature-list}})))
 
 (fn parse-h2-section [html]
   "parse a section that starts with an h2 tag. These are the main modules."
@@ -178,8 +200,8 @@
       (let [outfile (io.open (.. "src/fennel-ls/docs/lua" (version:gsub "%." "") ".fnl") :w)]
         (local {: view : sym : list} (require :fennel))
         (outfile:write
-          ";; Generated by make-docs.fnl. Contents come from " url "\n"
+          ";; Generated by make-docs.fnl from fennel-ls. Contents come from " url "\n"
-          ";; This lua manual was last updated " last-update "\n"
+          ";; The Lua manual for Lua " version " was last updated " last-update "\n"
           (view (list (sym :local) (sym :docs) docs))
           "\n"
           "(set docs._G.fields docs)\n"

test/completion.fnl

@@ -177,6 +177,7 @@
     [{:label :xyzzy :kind kinds.Variable :documentation true}] ;; TODO shouldn't this be kinds.Function
     [])
 
+  ;; things that aren't present in lua5.4 but are in other versions, I guess??
   (local things-that-are-allowed-to-have-missing-docs
     {:lua 1 :set-forcibly! 1 :unpack 1 :setfenv 1 :getfenv 1 :module 1 :newproxy 1 :gcinfo 1 :loadstring 1 :bit 1 :jit 1 :bit32 1})
 
@@ -221,7 +222,7 @@
 (fn test-module []
   (check "(coroutine.y|"
     [{:label "yield"
-      :documentation #(and $.value ($.value:find "```fnl\n(yield ...)\n```" 1 true))}]
+      :documentation #(and $.value ($.value:find "```fnl\n(coroutine.yield ...)\n```" 1 true))}]
     ["coroutine" "_G" "do"
      {:documentation #(= nil $)}])
   (check "(local c coroutine)
@@ -251,7 +252,7 @@
       :filterText "coroutine.yield"
       :insertText "coroutine.yield"
       :textEdit #(= nil $)
-      :documentation #(and $.value ($.value:find "```fnl\n(yield ...)\n```" 1 true))}]
+      :documentation #(and $.value ($.value:find "```fnl\n(coroutine.yield ...)\n```" 1 true))}]
     ["coroutine" "_G" "do"
      {:documentation #(= nil $)}]
     eglot)

test/hover.fnl

@@ -40,41 +40,43 @@
 
 (fn test-globals []
   (check "(pri|nt :hello :world)" "```fnl\n(print ...)\n```
-Receives any number of arguments and prints their values to `stdout`,
+Receives any number of arguments
-converting each argument to a string following the same rules of
+and prints their values to `stdout`,
-[`tostring`](https://lua.org/manual/5.4/manual.html#pdf-tostring).
+converting each argument to a string
+following the same rules of `tostring`.
 
-The function `print` is not intended for formatted output, but only as
+The function `print` is not intended for formatted output,
-a quick way to show a value, for instance for debugging. For complete
+but only as a quick way to show a value,
-control over the output, use
+for instance for debugging.
-[`string.format`](https://lua.org/manual/5.4/manual.html#pdf-string.format)
+For complete control over the output,
-and [`io.write`](https://lua.org/manual/5.4/manual.html#pdf-io.write).")
+use `string.format` and `io.write`.")
   (check "(local x print) (x| :hello :world)" "```fnl\n(print ...)\n```
-Receives any number of arguments and prints their values to `stdout`,
+Receives any number of arguments
-converting each argument to a string following the same rules of
+and prints their values to `stdout`,
-[`tostring`](https://lua.org/manual/5.4/manual.html#pdf-tostring).
+converting each argument to a string
+following the same rules of `tostring`.
 
-The function `print` is not intended for formatted output, but only as
+The function `print` is not intended for formatted output,
-a quick way to show a value, for instance for debugging. For complete
+but only as a quick way to show a value,
-control over the output, use
+for instance for debugging.
-[`string.format`](https://lua.org/manual/5.4/manual.html#pdf-string.format)
+For complete control over the output,
-and [`io.write`](https://lua.org/manual/5.4/manual.html#pdf-io.write).")
+use `string.format` and `io.write`.")
   (check "(xpca|ll io.open debug.traceback :filename.txt)" "```fnl
-(xpcall f msgh ...)
+(xpcall f msgh ?arg1 ...)
 ```
-This function is similar to [`pcall`](https://lua.org/manual/5.4/manual.html#pdf-pcall), except that it sets a
+This function is similar to `pcall`,
-new message handler `msgh`.")
+except that it sets a new message handler `msgh`.")
-  (check "(table.inser|t [] :message" #($:find "```fnl\n(insert list ?pos value)\n```" 1 true))
+  (check "(table.inser|t [] :message" #($:find "```fnl\n(table.insert list value)\n```" 1 true))
   nil)
 
 (fn test-module []
   (check "coroutine.yie|ld"
-         "```fnl\n(yield ...)\n```\nSuspends the execution of the calling coroutine.\nAny arguments to `yield` are passed as extra results to `resume`.")
+         "```fnl\n(coroutine.yield ...)\n```\nSuspends the execution of the calling coroutine.\nAny arguments to `yield` are passed as extra results to `resume`.")
   (check "string.cha|r"
-         "```fnl\n(char ...)\n```\nReceives zero or more integers.\nReturns a string with length equal to the number of arguments,\nin which each character has the internal numeric code equal\nto its corresponding argument.\n\nNumeric codes are not necessarily portable across platforms.")
+         "```fnl\n(string.char ...)\n```\nReceives zero or more integers.\nReturns a string with length equal to the number of arguments,\nin which each character has the internal numeric code equal\nto its corresponding argument.\n\nNumeric codes are not necessarily portable across platforms.")
   (check "(local x :hello)
           x.cha|r"
-         "```fnl\n(char ...)\n```\nReceives zero or more integers.\nReturns a string with length equal to the number of arguments,\nin which each character has the internal numeric code equal\nto its corresponding argument.\n\nNumeric codes are not necessarily portable across platforms."))
+         "```fnl\n(string.char ...)\n```\nReceives zero or more integers.\nReturns a string with length equal to the number of arguments,\nin which each character has the internal numeric code equal\nto its corresponding argument.\n\nNumeric codes are not necessarily portable across platforms."))
 
 
 (fn test-functions []