From 657947dc7cf01a13a4fa260691a6fa0147107950 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 20 Nov 2022 10:30:38 +0200 Subject: [PATCH] ; Improve recently-modified documentation * lisp/progmodes/python.el (python-base-mode) (python--treesit-fontify-string): * lisp/textmodes/css-mode.el (css-base-mode): * lisp/treesit.el (treesit-ready-p, treesit-comment-end) (treesit-simple-indent-presets): Fix typos and wording in doc strings. * doc/lispref/parsing.texi (Tree-sitter major modes): * doc/lispref/modes.texi (Parser-based Indentation): Fix wording and add cross-references. --- doc/lispref/modes.texi | 26 ++++++++++++++------------ doc/lispref/parsing.texi | 2 +- lisp/progmodes/python.el | 6 +++--- lisp/textmodes/css-mode.el | 2 +- lisp/treesit.el | 18 +++++++++--------- 5 files changed, 28 insertions(+), 26 deletions(-) diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 5e5eb458974..543fc48dd7a 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -4965,10 +4965,11 @@ first child where parent is @code{argument_list}, use @end example @item comment-end -This matcher is a function of 3 arguments: @var{node}, @var{parent}, -and @var{bol}, and returns non-@code{nil} if point is before a comment -ending token. Comment ending tokens are defined by regular expression -@code{treesit-comment-end}. +This matcher is a function that is called with 3 arguments: +@var{node}, @var{parent}, and @var{bol}, and returns non-@code{nil} if +point is before a comment ending token. Comment ending tokens are +defined by regular expression @code{treesit-comment-end} +(@pxref{Tree-sitter major modes, treesit-comment-end}). @item first-sibling This anchor is a function that is called with 3 arguments: @var{node}, @@ -4999,22 +5000,23 @@ This anchor is a function that is called with 3 arguments: @var{node}, charater on the previous line. @item point-min -This anchor is a function is called with 3 arguments: @var{node}, +This anchor is a function that is called with 3 arguments: @var{node}, @var{parent}, and @var{bol}, and returns the beginning of the buffer. This is useful as the beginning of the buffer is always at column 0. @item comment-start -This anchor is a function is called with 3 arguments: @var{node}, +This anchor is a function that is called with 3 arguments: @var{node}, @var{parent}, and @var{bol}, and returns the position right after the -opening comment token. Opening comment tokens are defined by regular -expression @code{treesit-comment-start}. This function assumes -@var{parent} is the comment node. +comment-start token. Comment-start tokens are defined by regular +expression @code{treesit-comment-start} (@pxref{Tree-sitter major +modes, treesit-comment-start}). This function assumes @var{parent} is +the comment node. @item coment-start-skip -This anchor is a function is called with 3 arguments: @var{node}, +This anchor is a function that is called with 3 arguments: @var{node}, @var{parent}, and @var{bol}, and returns the position after the -opening comment token, after skipping forward any whitespace -characters. Opening comment tokens are defined by regular expression +comment-start token and any whitespace characters following that +token. Comment-start tokens are defined by regular expression @code{treesit-comment-start}. This function assumes @var{parent} is the comment node. @end ftable diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index bea358f2b0c..f21d94ec8b3 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -1735,7 +1735,7 @@ For example, it should match @samp{//}, @samp{////}, @samp{/*}, @end defvar @defvar treesit-comment-end -This should be a regular expression matching an closing comment token. +This should be a regular expression matching a closing comment token. For example, it should match @samp{*/}, @samp{****/}, etc., in C. @end defvar diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el index d16aeaf0133..2f967ebab24 100644 --- a/lisp/progmodes/python.el +++ b/lisp/progmodes/python.el @@ -1016,7 +1016,7 @@ It makes underscores and dots word constituent chars.") "Fontify string. NODE is the string node. Do not fontify the initial f for f-strings. OVERRIDE is the override flag described in -`treesit-font-lock-rules'. START and END marks the region to be +`treesit-font-lock-rules'. START and END mark the region to be fontified." (let* ((string-beg (treesit-node-start node)) (string-end (treesit-node-end node)) @@ -6482,8 +6482,8 @@ Add import for undefined name `%s' (empty to skip): " (define-derived-mode python-base-mode prog-mode "Python" "Generic major mode for editing Python files. -This is a generic major mode intended to be inherited by a -concrete implementations. Currently there two concrete +This is a generic major mode intended to be inherited by +concrete implementations. Currently there are two concrete implementations: `python-mode' and `python-ts-mode'." (setq-local tab-width 8) (setq-local indent-tabs-mode nil) diff --git a/lisp/textmodes/css-mode.el b/lisp/textmodes/css-mode.el index 34380c05a00..6915e499bba 100644 --- a/lisp/textmodes/css-mode.el +++ b/lisp/textmodes/css-mode.el @@ -1751,7 +1751,7 @@ rgb()/rgba()." "Generic mode to edit Cascading Style Sheets (CSS). This is a generic major mode intended to be inherited by a -concrete implementation. Currently there two concrete +concrete implementation. Currently there are two concrete implementations: `css-mode' and `css-ts-mode'." (setq-local comment-start "/*") (setq-local comment-start-skip "/\\*+[ \t]*") diff --git a/lisp/treesit.el b/lisp/treesit.el index 76cefbbaf32..674c984dfe5 100644 --- a/lisp/treesit.el +++ b/lisp/treesit.el @@ -822,15 +822,15 @@ parser notifying of the change." ;;; Indent -;; `comment-start' and `comment-end' assumes there is only one type of -;; comment and comment spans only one line. So they are not +;; `comment-start' and `comment-end' assume there is only one type of +;; comment, and that the comment spans only one line. So they are not ;; sufficient for our purpose. (defvar-local treesit-comment-start nil "Regular expression matching an opening comment token.") (defvar-local treesit-comment-end nil - "Regular expression matching an closing comment token.") + "Regular expression matching a closing comment token.") (define-error 'treesit-indent-error "Generic tree-sitter indentation error" @@ -1069,14 +1069,14 @@ point-min comment-start - Returns the ending position after matching `treesit-comment-start'. - Assuming PARENT is a comment node. + Returns the position after a match for `treesit-comment-start'. + Assumes PARENT is a comment node. comment-start-skip - Goes to the position comment-start would return, skip - whitespaces forward, and return the resulting position. - Assuming PARENT is a comment node.") + Goes to the position that comment-start would return, skips + whitespace after that, and returns the resulting position. + Assumes PARENT is a comment node.") (defun treesit--simple-indent-eval (exp) "Evaluate EXP. @@ -1463,7 +1463,7 @@ LANGUAGE is the language symbol to check for availability. It can also be a list of language symbols. If tree-sitter is not ready, emit a warning and return nil. If -the user has chosen to activate tree-sitter for MODE and +the user has chosen to activate tree-sitter for LANGUAGE and tree-sitter is ready, return non-nil. If QUIET is t, don't emit warning in either case; if quiet is `message', display a message instead of emitting warning." -- 2.39.5