From bb337181f978cd4f2c94520cafcd2ebfbbf528f6 Mon Sep 17 00:00:00 2001 From: Josh Goebel Date: Mon, 11 Nov 2019 23:49:54 -0500 Subject: [PATCH] clarify use of continuation --- docs/api.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index d8039539d3..8950b6adfb 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -14,7 +14,13 @@ forces highlighting to finish even in case of detecting illegal syntax for the language instead of throwing an exception. The ``continuation`` is an optional mode stack representing unfinished parsing. When present, the function will restart parsing from this state instead of -initializing a new one. +initializing a new one. This is used internally for `sublanguage` support. + +Note: `continuation` is NOT intended to support line-by-line highlighting +because there is no requirement that a grammar handle linebreaks in any special +way. It's quite possible for a grammar to have a single mode/regex that matches +MANY lines at once. This is not discouraged and entirely up to the grammar. + Returns an object with the following properties: * ``language``: language name, same as the one passed into a function, returned for consistency with ``highlightAuto``