1// Copyright 2023 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5Notes on the format of the testcase files in
6cmd/compile/internal/inline/inlheur/testdata/props:
7
8- each (compilable) file contains input Go code and expected results
9  in the form of column-0 comments.
10
11- functions or methods that begin with "T_" are targeted for testing,
12  as well as "init" functions; all other functions are ignored.
13
14- function header comments begin with a line containing
15  the file name, function name, definition line, then index
16  and a count of the number of funcs that share that same
17  definition line (needed to support generics). Example:
18
19	  // foo.go T_mumble 35 1 4
20
21  Here "T_mumble" is defined at line 35, and it is func 0
22  out of the 4 funcs that share that same line.
23
24- function property expected results appear as comments in immediately
25  prior to the function. For example, here we have first the function
26  name ("T_feeds_if_simple"), then human-readable dump of the function
27  properties, as well as the JSON for the properties object, each
28  section separated by a "<>" delimiter.
29
30	  // params.go T_feeds_if_simple 35 0 1
31	  // RecvrParamFlags:
32	  //   0: ParamFeedsIfOrSwitch
33	  // <endpropsdump>
34	  // {"Flags":0,"RecvrParamFlags":[8],"ReturnFlags":[]}
35	  // callsite: params.go:34:10|0 "CallSiteOnPanicPath" 2
36	  // <endcallsites>
37	  // <endfuncpreamble>
38	  func T_feeds_if_simple(x int) {
39		if x < 100 {
40			os.Exit(1)
41		}
42		println(x)
43	}
44
45- when the test runs, it will compile the Go source file with an
46  option to dump out function properties, then compare the new dump
47  for each function with the JSON appearing in the header comment for
48  the function (in the example above, the JSON appears between
49  "<endpropsdump>" and "<endfuncpreamble>". The material prior to the
50  dump is simply there for human consumption, so that a developer can
51  easily see that "RecvrParamFlags":[8] means that the first parameter
52  has flag ParamFeedsIfOrSwitch.
53
54- when making changes to the compiler (which can alter the expected
55  results) or edits/additions to the go code in the testcase files,
56  you can remaster the results by running
57
58    go test -v -count=1 .
59
60  In the trace output of this run, you'll see messages of the form
61
62      === RUN   TestFuncProperties
63       funcprops_test.go:NNN: update-expected: emitted updated file
64                              testdata/props/XYZ.go.new
65       funcprops_test.go:MMM: please compare the two files, then overwrite
66                              testdata/props/XYZ.go with testdata/props/XYZ.go.new
67
68  at which point you can compare the old and new files by hand, then
69  overwrite the *.go file with the *.go.new file if you are happy with
70  the diffs.
71
72- note that the remastering process will strip out any existing
73  column-0 (unindented) comments; if you write comments that you
74  want to see preserved, use "/* */" or indent them.
75
76
77
78