>> --- a/doc/emacs/text.texi >> +++ b/doc/emacs/text.texi >> @@ -1097,6 +1097,11 @@ Outline Format >> chapters. This works as long as no other command starts with >> @samp{@@chap}. >> >> +@vindex outline-search-function >> + Instead of setting the variable @code{outline-regexp}, you can set >> +the variable @code{outline-search-function} to a function that >> +matches the current heading and searches for the next one. > > This should tell which arguments will be passed to the function, and > what it is expected to do and return. This is the Emacs User Manual, not the Emacs Lisp Reference Manual. Are you sure that arguments should be described here? >> +(defvar-local treesit-outline-predicate nil >> + "Predicate used to find outline headings in the syntax tree. >> +Intended to be set by a major mode. When nil, the predicate >> +is constructed from the value of `treesit-simple-imenu-settings' >> +when a major mode sets it.") > > The doc string should explain with what arguments will the predicate > be called and when it is expected to return non-nil. Fixed. >> +(defun treesit-outline-predicate-from-imenu (node) >> + "Return an outline searching predicate created from Imenu. >> +Return the value suitable to set `treesit-outline-predicate'. >> +Create this predicate from the value `treesit-simple-imenu-settings' >> +that major modes set to find Imenu entries. The assumption here >> +is that the positions of Imenu entries most of the time coincide >> +with the lines of outline headings. When this assumption fails, >> +you can directly set a proper value to `treesit-outline-predicate'." > > Likewise here: please describe in the doc string the signature and > expectations from the predicate returned by this function (or point to > the doc of some other variable/function where that information is > included). Actually, this is an internal function and doesn't need a docstring at all. So I added two slashes to its name, and demoted its docstring to comments. >> +(defun treesit-outline-search (&optional bound move backward looking-at) >> + "Search for the next outline heading in the syntax tree. >> +See the descriptions of arguments in `outline-search-function'." > > What about the return value (if it is important)? The return value is described in the docstring of `outline-search-function' where the docstring above links to.