cmd/compile: document new line directives

Fixes #24183.

Change-Id: I5ef31c4a3aad7e05568b7de1227745d686d4aff8
Reviewed-on: https://go-review.googlesource.com/100462
Reviewed-by: Ian Lance Taylor <iant@golang.org>

src/cmd/compile/doc.go

@@ -100,22 +100,54 @@ for a usage message.
 
 Compiler Directives
 
-The compiler accepts compiler directives in the form of // comments at the
-beginning of a line. To distinguish them from non-directive comments, the directives
-require no space between the slashes and the name of the directive. However, since
+The compiler accepts directives in the form of comments.
+To distinguish them from non-directive comments, directives
+require no space between the comment opening and the name of the directive. However, since
 they are comments, tools unaware of the directive convention or of a particular
 directive can skip over a directive like any other comment.
-
-	//line path/to/file:linenumber
-
-The //line directive specifies that the source line that follows should be recorded
-as having come from the given file path and line number. Successive lines are
-recorded using increasing line numbers, until the next directive. This directive
-typically appears in machine-generated code, so that compilers and debuggers
-will show lines in the original input to the generator.
-
-The //line directive is an historical special case; all other directives are of the form
-//go:name, indicating that the directive is defined by the Go toolchain.
+*/
+// Line directives come in several forms:
+//
+// 	//line :line
+// 	//line :line:col
+// 	//line filename:line
+// 	//line filename:line:col
+// 	/*line :line*/
+// 	/*line :line:col*/
+// 	/*line filename:line*/
+// 	/*line filename:line:col*/
+//
+// In order to be recognized as a line directive, the comment must start with
+// //line or /*line followed by a space, and must contain at least one colon.
+// The //line form must start at the beginning of a line.
+// A line directive specifies the source position for the character immediately following
+// the comment as having come from the specified file, line and column:
+// For a //line comment, this is the first character of the next line, and
+// for a /*line comment this is the character position immediately following the closing */.
+// If no filename is given, the recorded filename is empty if there is also no column number;
+// otherwise is is the most recently recorded filename (actual filename or filename specified
+// by previous line directive).
+// If a line directive doesn't specify a column number, the column is "unknown" until
+// the next directive and the compiler does not report column numbers for that range.
+// The line directive text is interpreted from the back: First the trailing :ddd is peeled
+// off from the directive text if ddd is a valid number > 0. Then the second :ddd
+// is peeled off the same way if it is valid. Anything before that is considered the filename
+// (possibly including blanks and colons). Invalid line or column values are reported as errors.
+//
+// Examples:
+//
+//	//line foo.go:10      the filename is foo.go, and the line number is 10 for the next line
+//	//line C:foo.go:10    colons are permitted in filenames, here the filename is C:foo.go, and the line is 10
+//	//line  a:100 :10     blanks are permitted in filenames, here the filename is " a:100 " (excluding quotes)
+//	/*line :10:20*/x      the position of x is in the current file with line number 10 and column number 20
+//	/*line foo: 10 */     this comment is recognized as invalid line directive (extra blanks around line number)
+//
+// Line directives typically appear in machine-generated code, so that compilers and debuggers
+// will report positions in the original input to the generator.
+/*
+The line directive is an historical special case; all other directives are of the form
+//go:name and must start at the begnning of a line, indicating that the directive is defined
+by the Go toolchain.
 
 	//go:noescape