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