docs: add docs

.github/workflows/docs.yaml

@@ -0,0 +1,26 @@
+name: Generate documentation
+
+permissions:
+  contents: write
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'ldoc/**.lua'
+
+jobs:
+  docs-master:
+    name: Generate master documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+      - name: Run LDoc
+        uses: lunarmodules/[email protected]
+      - name: Deploy to Github Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./doc

.gitignore

@@ -39,3 +39,5 @@ luac.out
 *.x86_64
 *.hex
 
+# ldoc output
+doc/

config.ld

@@ -0,0 +1,13 @@
+file = {
+	'ldoc/init.lua',
+	'ldoc/Language.lua',
+	'ldoc/Node.lua',
+	'ldoc/Parser.lua',
+	'ldoc/Point.lua',
+	'ldoc/Tree.lua',
+}
+project = 'lua-tree-sitter'
+description = 'Lua bindings for Tree-sitter'
+title = 'lua-tree-sitter Reference'
+dir = 'doc'
+format = 'markdown'

ldoc/Language.lua

@@ -0,0 +1,35 @@
+---
+-- A language definition used by a `Parser` to parse a document.
+-- Analogous to `TSLanguage`.
+-- @classmod Language
+-- @pragma nostrip
+
+---
+-- Functions
+-- @section Functions
+
+---
+-- Load a language from a dynamic library.
+-- @tparam string path path to the dynamic library
+-- @tparam string name name of the language
+-- @treturn Language language definition
+function Language.new(path, name) end
+
+---
+-- Methods
+-- @section Methods
+
+---
+-- Get the ABI version number for this language.
+-- @treturn integer version
+function Language:version() end
+
+---
+-- Metamethods
+-- @section Metamethods
+
+---
+-- Check equality of two languages.
+-- @tparam Language other
+-- @treturn bool
+function Language:__eq(other) end

ldoc/Node.lua

@@ -0,0 +1,29 @@
+---
+-- A node within a `Tree`.
+-- Analogous to `TSNode`.
+-- @classmod Node
+-- @pragma nostrip
+
+---
+-- Methods
+-- @section Methods
+
+---
+-- Get the `Tree` the node belongs to.
+-- @treturn Node
+function Node:tree() end
+
+---
+-- Metamethods
+-- @section Metamethods
+
+---
+-- Check equality of two nodes by value.
+-- @tparam Node other
+-- @treturn bool
+function Node:__eq(other) end
+
+---
+-- Convert the node to a S-expression.
+-- @treturn string
+function Node:__tostring() end

ldoc/Parser.lua

@@ -0,0 +1,59 @@
+---
+-- Parses a document based on a `Language` to produce a `Tree`.
+-- Analogous to `TSParser`.
+-- @classmod Parser
+-- @pragma nostrip
+
+---
+-- Functions
+-- @section Functions
+
+---
+-- Create a new parser.
+-- @treturn Parser
+function Parser.new() end
+
+---
+-- Methods
+-- @section Methods
+
+---
+-- Get the parser's current language.
+-- @treturn Language
+function Parser:language() end
+
+---
+-- Set the language that the parser should use for parsing.
+-- @tparam Language lang
+function Parser:set_language(lang) end
+
+---
+-- Use the parser to parse some source code and create a syntax tree.  
+-- If you are parsing this document for the first time, pass `nil` for the
+-- `old_tree` parameter.
+--
+-- Otherwise, pass the previous syntax tree for the `old_tree` parameter.
+-- For this to work correctly, you must have already edited the old syntax tree
+-- using `Tree:edit` so that it matches the source code changes.
+--
+-- The reader function takes a byte offset and a `Point`,
+-- and returns a a chunk of text that starts at the point given.
+-- Return an empty `string` or `nil` to signal end of the document.
+-- @tparam Tree old_tree edited syntax tree
+-- @tparam func read reader function
+-- @treturn Tree
+-- @see Parser.parse_
+function Parser:parse(old_tree, read) end
+
+---
+-- Like `Parser.parse`, but the `read` function returns a `string`, and a
+-- second integer value representing the offset at which the requested chunk of
+-- text starts within the string.
+--
+-- This is provided so you can avoid having to create substrings, improving
+-- performance.
+-- @tparam Tree old_tree edited syntax tree
+-- @tparam func read reader function
+-- @treturn Tree
+-- @see Parser.parse
+function Parser:parse_(old_tree, read) end

ldoc/Point.lua

@@ -0,0 +1,54 @@
+---
+-- A point on a document.
+-- Analogous to `TSPoint`.
+-- @classmod Point
+-- @pragma nostrip
+
+---
+-- Functions
+-- @section Functions
+
+---
+-- Create a new point.
+-- @tparam integer row
+-- @tparam integer column
+-- @treturn Point
+function Point.new(row, column) end
+
+---
+-- Alias for `new`.
+-- @tparam integer row
+-- @tparam integer column
+-- @treturn Point
+-- @see new
+function Point.pack(row, column) end
+
+---
+-- Methods
+-- @section Methods
+
+---
+-- Unpack the point.
+-- @treturn integer row
+-- @treturn integer column
+function Point:unpack() end
+
+---
+-- Get the row of the point.
+-- @treturn integer
+function Point:row() end
+
+---
+-- Get the column of the point.
+-- @treturn integer
+function Point:column() end
+
+---
+-- Metamethods
+-- @section Metamethods
+
+---
+-- Check equality of two points by value.
+-- @tparam Point other
+-- @treturn bool
+function Point:__eq(other) end

ldoc/Tree.lua

@@ -0,0 +1,64 @@
+---
+-- A syntax tree.
+-- Analogous to `TSTree`.
+-- @classmod Tree
+-- @pragma nostrip
+
+---
+-- Methods
+-- @section Methods
+
+---
+-- Create a shallow copy of the syntax tree.
+--
+-- You need to copy a syntax tree in order to use it on more than one thread at
+-- a time, as syntax trees are not thread safe.
+-- @treturn Tree
+function Tree:copy() end
+
+---
+-- Get the root node of the syntax tree.
+-- @treturn Node
+function Tree:root_node() end
+
+---
+-- Get the language that was used to parse the syntax tree.
+-- @treturn Language
+-- @see Parser:set_language
+function Tree:language() end
+
+---
+-- Get the array of included ranges that was used to parse the syntax tree.
+-- @treturn RangeArray
+-- @see Parser:set_included_ranges
+function Tree:included_ranges() end
+
+---
+-- Edit the syntax tree to keep it in sync with source code that has been
+-- edited.
+--
+-- The edits have to be described in **both** byte offsets and `Point`s.
+-- @tparam integer start_byte
+-- @tparam integer old_end_byte
+-- @tparam integer new_end_byte<br/>
+-- @tparam Point start_point
+-- @tparam Point old_end_point
+-- @tparam Point new_end_point
+function Tree:edit(
+	start_byte, old_end_byte, new_end_byte,
+	start_point, old_end_point, new_end_point
+) end
+
+---
+-- Metamethods
+-- @section Metamethods
+
+---
+-- Check equality of two trees by their root node.
+--
+-- Equivalent to calling `Node:__eq` on the two root nodes.
+-- @tparam Tree other
+-- @treturn bool
+-- @see root_node
+-- @see Node.__eq
+function Tree:__eq(other) end

ldoc/init.lua

@@ -0,0 +1,5 @@
+---
+-- Require only this module, as all classes reside as fields within this module
+-- @module tree_sitter
+-- @usage
+-- local ts = require 'tree_sitter'