patch 8.2.1227: Vim9: allowing both quoted and # comments is confusingv8.2.1227

Problem:    Vim9: allowing both quoted and # comments is confusing.
Solution:   Only support # comments in Vim9 script.

1 files changed, 18 insertions, 11 deletions

diff --git a/runtime/doc/vim9.txt b/runtime/doc/vim9.txt
index ad96817ff1..748dd7cd55 100644
--- a/runtime/doc/vim9.txt
+++ b/runtime/doc/vim9.txt
@@ -1,4 +1,4 @@
-*vim9.txt*	For Vim version 8.2.  Last change: 2020 Jul 10
+*vim9.txt*	For Vim version 8.2.  Last change: 2020 Jul 17
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -64,20 +64,24 @@ THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
 
 Comments starting with # ~
 
-In Vim script comments start with double quote.  That can also be the start of
-a string, thus in many places it cannot be used.  In Vim9 script a comment
-normally starts with #.  In Vi this is a command to list text with numbers,
-but you can also use `:number` for that. >
+In legacy Vim script comments start with double quote.  In Vim9 script
+comments start with #. >
+	# declarations
 	let count = 0  # number of occurrences
 
-To improve readability there must be a space between the command and the #
+The reason is that a double quote can also be the start of a string. In many
+places, especially halfway an expression with a line break, it's hard to tell
+what the meaning is.  To avoid confusion only # comments are recognized.
+This is the same as in shell scripts and Python programs.
+
+In Vi # is a command to list text with numbers.  In Vim9 script you can use
+`:number` for that. >
+	101number
+
+To improve readability there must be a space between a command and the #
 that starts a comment.  Note that #{ is the start of a dictionary, therefore
 it cannot start a comment.
 
-Since Vim9 script allows for line breaks in many places, the double quoted
-comment also cannot be used at the start of a line after an expression.  To
-avoid confusion it is best to only use # comments.
-
 
 Vim9 functions ~
 
@@ -400,6 +404,7 @@ The boolean operators "||" and "&&" do not change the value: >
 	0 || ''  == ''
 	8 && 2   == 2
 	0 && 2   == 0
+	2 && 0   == 0
 	[] && 2  == []
 
 When using `..` for string concatenation the arguments are always converted to
@@ -418,13 +423,15 @@ be made.  Here is a summary of what might be unexpected.
 
 Ex command ranges need to be prefixed with a colon. >
   	->		" legacy Vim: shifts the previous line to the right
-	->func()	" Vim9: method call
+	->func()	" Vim9: method call in continuation line
 	:->		" Vim9: shifts the previous line to the right
 
 	%s/a/b		" legacy Vim: substitute on all lines
 	x = alongname
 	     % another	" Vim9: line continuation without a backslash
 	:%s/a/b		" Vim9: substitute on all lines
+	'text'->func()	" Vim9: method call
+	:'t		" legacy Vim: jump to mark m
 
 Functions defined with `:def` compile the whole function.  Legacy functions
 can bail out, and the following lines are not parsed: >