From: Yuan Fu <casouri@gmail.com>
Date: Thu, 14 Sep 2023 01:14:03 +0000 (-0700)
Subject: Improve docstring for treesit-language-at
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=8facdb62d3e7e42a36cbbd164be93e72d1ce2663;p=emacs.git

Improve docstring for treesit-language-at

* lisp/treesit.el (treesit-language-at-point-function)
(treesit-language-at): Several people has confused over this, make it
extra clear than treesit-language-at requires
treesit-language-at-point-function to work.
---

diff --git a/lisp/treesit.el b/lisp/treesit.el
index f65e2e02a7c..520fff04f80 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -136,14 +136,23 @@ Return the root node of the syntax tree."
 This is used by `treesit-language-at', which is used by various
 functions to determine which parser to use at point.
 
-The function is called with one argument, the position of point.")
+The function is called with one argument, the position of point.
+
+In general, this function should call `treesit-node-at' with an
+explicit language (usually the host language), and determine the
+language at point using the type of the returned node.")
 
 (defun treesit-language-at (position)
   "Return the language at POSITION.
+
 This function assumes that parser ranges are up-to-date.  It
 returns the return value of `treesit-language-at-point-function'
 if it's non-nil, otherwise it returns the language of the first
-parser in `treesit-parser-list', or nil if there is no parser."
+parser in `treesit-parser-list', or nil if there is no parser.
+
+In a multi-language buffer, make sure
+`treesit-language-at-point-function' is implemented!  Otherwise
+`treesit-language-at' wouldn't return the correct result."
   (if treesit-language-at-point-function
       (funcall treesit-language-at-point-function position)
     (when-let ((parser (car (treesit-parser-list))))