From e65d6a6abe1ea4731dcb86f02fd7a68e97ed97eb Mon Sep 17 00:00:00 2001 From: Robert Griesemer Date: Tue, 13 Mar 2018 16:08:16 -0700 Subject: [PATCH] cmd/compile: document new line directives Fixes #24183. Change-Id: I5ef31c4a3aad7e05568b7de1227745d686d4aff8 Reviewed-on: https://go-review.googlesource.com/100462 Reviewed-by: Ian Lance Taylor --- src/cmd/compile/doc.go | 60 ++++++++++++++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 14 deletions(-) diff --git a/src/cmd/compile/doc.go b/src/cmd/compile/doc.go index 83bd36c34c..0dfaacb584 100644 --- a/src/cmd/compile/doc.go +++ b/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 -- 2.48.1