abidiff: Document and refresh tests.

Following on from giving some test file more descriptive names, this
patch actually documents in brief the purpose of these recently added
tests.

It also improves the coverage of the test-leaf-cxx-members test to
include deletion and insertion report text as well.

	* tests/data/test-abidiff-exit/test-leaf-cxx-members-v1.cc:
	Comment test. Reorder members of ops to get better coverage.
	* tests/data/test-abidiff-exit/test-leaf-fun-type-v1.cc:
	Comment test.
	* tests/data/test-abidiff-exit/test-leaf-more-v1.cc: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-peeling-v1.cc:
	Comment test. Update comment on ops2.
	* tests/data/test-abidiff-exit/test-leaf-redundant-v1.c:
	Comment test.
	* tests/data/test-abidiff-exit/test-leaf-stats-v1.cc: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-cxx-members-report.txt:
	Update locations. Update report to reflect deletion,
	insertion and changed members (was previously changed only).:
	* tests/data/test-abidiff-exit/test-leaf-peeling-report.txt:
	Update locations.
	* tests/data/test-abidiff-exit/test-leaf-redundant-report.txt:
	Ditto.:
	* tests/data/test-abidiff-exit/test-leaf-cxx-members-v0.cc:
	Added one line comment referring to -v1 source file.
	* tests/data/test-abidiff-exit/test-leaf-fun-type-v0.cc: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-more-v0.cc: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-peeling-v0.cc: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-redundant-v0.c: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-stats-v0.cc: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-cxx-members-v0.o: Recompiled.
	* tests/data/test-abidiff-exit/test-leaf-cxx-members-v1.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-fun-type-v0.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-fun-type-v1.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-more-v0.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-more-v1.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-peeling-v0.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-peeling-v1.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-redundant-v0.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-redundant-v1.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-stats-v0.o: Ditto.
	* tests/data/test-abidiff-exit/test-leaf-stats-v1.o: Ditto.

Signed-off-by: Giuliano Procida <gprocida@google.com>

tests/data/test-abidiff-exit/test-leaf-cxx-members-report.txt

@@ -15,28 +15,27 @@ Removed/Changed/Added variables summary: 0 Removed, 0 Changed, 0 Added variable
 
 1 function with some sub-type change:
 
-  [C] 'method virtual int ops::changed_fn()' at test-leaf-cxx-members-v1.cc:6:1 has some sub-type changes:
+  [C] 'method virtual int ops::changed_fn()' at test-leaf-cxx-members-v1.cc:5:1 has some sub-type changes:
     return type changed:
       type name changed from 'int' to 'long int'
       type size changed from 32 to 64 (in bits)
 
-'struct ops at test-leaf-cxx-members-v0.cc:1:1' changed:
+'struct ops at test-leaf-cxx-members-v0.cc:2:1' changed:
   type size changed from 128 to 192 (in bits)
   1 member function deletion:
-    'method virtual int ops::deleted_fn()' at test-leaf-cxx-members-v0.cc:3:1, virtual at voffset 0/1    {_ZN3ops10deleted_fnEv}
+    'method virtual int ops::deleted_fn()' at test-leaf-cxx-members-v0.cc:6:1, virtual at voffset 1/1    {_ZN3ops10deleted_fnEv}
   1 member function insertion:
-    'method virtual long int ops::added_fn()' at test-leaf-cxx-members-v1.cc:3:1, virtual at voffset 0/1    {_ZN3ops8added_fnEv}
+    'method virtual long int ops::added_fn()' at test-leaf-cxx-members-v1.cc:11:1, virtual at voffset 1/1    {_ZN3ops8added_fnEv}
   there are member function changes:
     'method virtual int ops::changed_fn()' has some changes:
       return type changed:
         type name changed from 'int' to 'long int'
         type size changed from 32 to 64 (in bits)
+  1 data member deletion:
+    'int ops::deleted_var', at offset 96 (in bits) at test-leaf-cxx-members-v0.cc:5:1
+  1 data member insertion:
+    'long int ops::added_var', at offset 128 (in bits) at test-leaf-cxx-members-v1.cc:10:1
   there are data member changes:
-    type 'int' of 'ops::deleted_var' changed:
-      type name changed from 'int' to 'long int'
-      type size changed from 32 to 64 (in bits)
-    and name of 'ops::deleted_var' changed to 'ops::added_var' at test-leaf-cxx-members-v1.cc:2:1
     type 'int' of 'ops::changed_var' changed:
       type name changed from 'int' to 'long int'
       type size changed from 32 to 64 (in bits)
-    and offset changed from 96 to 128 (in bits) (by +32 bits)

tests/data/test-abidiff-exit/test-leaf-cxx-members-v0.cc

@@ -1,9 +1,9 @@
+// See comments in -v1.c file.
 struct ops {
-  int deleted_var;
-  virtual int deleted_fn() { return 0; }
-
   int changed_var;
   virtual int changed_fn() { return 0; }
+  int deleted_var;
+  virtual int deleted_fn() { return 0; }
 };
 
 void reg(ops& x) {

tests/data/test-abidiff-exit/test-leaf-cxx-members-v1.cc

@@ -1,11 +1,14 @@
+// Exercises the reporting of struct differences in --leaf-changes-only mode.
+// The resulting report should have no excess blank lines.
 struct ops {
-  // TODO: type, name and size are differnent from deleted_var, but this is
-  // still reported as a change rather than a deletion and an addition.
+  long changed_var;  // was int
+  virtual long changed_fn() { return 0; }  // was int
+  // Note that in order for this to be treated as an addition, as opposed to a
+  // change, we need to make sure it's at a different offset from anything in
+  // the old version of ops; having type, name and size different but the same
+  // offset won't work.
   long added_var;
   virtual long added_fn() { return 0; }
-
-  long changed_var;
-  virtual long changed_fn() { return 0; }
 };
 
 void reg(ops& x) {

tests/data/test-abidiff-exit/test-leaf-fun-type-v0.cc

@@ -1,3 +1,4 @@
+// See comments in -v1.c file.
 struct ops {
   void (*munge)(int x);
 };

tests/data/test-abidiff-exit/test-leaf-fun-type-v1.cc

@@ -1,5 +1,7 @@
+// The change to ops::munge is local to ops and should result in ops being
+// reported as a changed type in --leaf-changes-only mode.
 struct ops {
-  char (*munge)(long x, bool gunk);
+  char (*munge)(long x, bool gunk);  // everything but the name changed
 };
 
 void register_ops(const ops&) {

tests/data/test-abidiff-exit/test-leaf-more-v0.cc

@@ -1,3 +1,4 @@
+// See comments in -v1.c file.
 struct changed {
   int foo = 0;
 };

tests/data/test-abidiff-exit/test-leaf-more-v1.cc

@@ -1,12 +1,14 @@
+// Ensure that local changes to functions and variables (including their removal
+// or addition) are reported in --leaf-changes-only mode.
 struct changed {
-  long foo = 0;
+  long foo = 0;  // was int
 };
 
-long directly_changed_var = 0;
+long directly_changed_var = 0;  // was int
 changed * indirectly_changed_var;
 long added_var = 0;
 
-long directly_changed_fun() {
+long directly_changed_fun() {  // was int
   return 0;
 }
 void indirectly_changed_fun(changed * x) {

tests/data/test-abidiff-exit/test-leaf-peeling-report.txt

@@ -3,38 +3,38 @@ Changed leaf types summary: 6 leaf types changed
 Removed/Changed/Added functions summary: 0 Removed, 0 Changed, 0 Added function
 Removed/Changed/Added variables summary: 0 Removed, 0 Changed, 0 Added variable
 
-'struct foo at test-leaf-peeling-v0.cc:1:1' changed:
+'struct foo at test-leaf-peeling-v0.cc:2:1' changed:
   type size changed from 32 to 64 (in bits)
   there are data member changes:
     type 'int' of 'foo::z' changed:
       type name changed from 'int' to 'long int'
       type size changed from 32 to 64 (in bits)
 
-'struct ops1 at test-leaf-peeling-v0.cc:5:1' changed:
+'struct ops1 at test-leaf-peeling-v0.cc:6:1' changed:
   type size hasn't changed
   there are data member changes:
     type 'int*' of 'ops1::x' changed:
       pointer type changed from: 'int*' to: 'int**'
 
-'struct ops2 at test-leaf-peeling-v0.cc:9:1' changed:
+'struct ops2 at test-leaf-peeling-v0.cc:10:1' changed:
   type size changed from 320 to 640 (in bits)
   there are data member changes:
     'foo ops2::y[10]' size changed from 320 to 640 (in bits) (by +320 bits)
 
-'struct ops3 at test-leaf-peeling-v0.cc:13:1' changed:
+'struct ops3 at test-leaf-peeling-v0.cc:14:1' changed:
   type size hasn't changed
   there are data member changes:
     type 'void (int&)*' of 'ops3::spong' changed:
       pointer type changed from: 'void (int&)*' to: 'void (int&&)*'
 
-'struct ops4 at test-leaf-peeling-v0.cc:17:1' changed:
+'struct ops4 at test-leaf-peeling-v0.cc:18:1' changed:
   type size hasn't changed
   there are data member changes:
     type 'int*' of 'ops4::x' changed:
       entity changed from 'int*' to 'int&'
       type size hasn't changed
 
-'struct ops5 at test-leaf-peeling-v0.cc:21:1' changed:
+'struct ops5 at test-leaf-peeling-v0.cc:22:1' changed:
   type size hasn't changed
   there are data member changes:
     type 'int*' of 'ops5::x' changed:

tests/data/test-abidiff-exit/test-leaf-peeling-v0.cc

@@ -1,3 +1,4 @@
+// See comments in -v1.c file.
 struct foo {
   int z;
 };

tests/data/test-abidiff-exit/test-leaf-peeling-v1.cc

@@ -1,33 +1,35 @@
+// Ensure that different pointer / reference types are considered genuinely
+// different in --leaf-changes-only mode.
 struct foo {
-  long z;
+  long z;  // was int
 };
 
 struct ops1 {
-  int ** x;
+  int ** x;  // was *
 };
 
 struct ops2 {
-  // A change to foo's size is currently considered local here.  Arguably this
-  // should be considered non-local as the change to foo is being reported
-  // independently.  If this happens, the test case will need to be updated (to
-  // remove the reporting of an ops5 diff).
+  // A change to foo's size (impacting y's size) is currently considered local
+  // here.  Arguably this should be considered non-local as the change to foo is
+  // also being reported independently.  If this happens, the test case will
+  // need to be updated (to remove the reporting of the ops2 diff).
   foo y[10];
 };
 
 struct ops3 {
-  void (*spong)(int && wibble);
+  void (*spong)(int && wibble);  // was &
 };
 
 struct ops4 {
-  int & x;
+  int & x;  // was *
 };
 
 struct ops5 {
-  int *** x;
+  int *** x;  // was *
 };
 
 // TODO: This *should* be considered a local change, but currently is not.
-int var6[5][2];
+int var6[5][2];  // was [2][5]
 
 void register_ops1(ops1*) { }
 void register_ops2(ops2*) { }

tests/data/test-abidiff-exit/test-leaf-redundant-report.txt

@@ -5,23 +5,23 @@ Removed/Changed/Added variables summary: 0 Removed, 0 Changed, 0 Added variable
 
 4 functions with some sub-type change:
 
-  [C] 'function void fn1(sto1)' at test-leaf3-v1.c:10:1 has some sub-type changes:
+  [C] 'function void fn1(sto1)' at test-leaf-redundant-v1.c:12:1 has some sub-type changes:
     parameter 1 of type 'struct sto1' changed:
       type name changed from 'sto1' to 'stn1'
       type size hasn't changed
 
-  [C] 'function void fn2(sto2)' at test-leaf3-v1.c:13:1 has some sub-type changes:
+  [C] 'function void fn2(sto2)' at test-leaf-redundant-v1.c:15:1 has some sub-type changes:
     parameter 1 of type 'struct sto2' changed:
       type name changed from 'sto2' to 'stn2'
       type size changed from 64 to 128 (in bits)
       1 data member insertion:
-        'double stn2::y', at offset 64 (in bits) at test-leaf3-v1.c:7:1
+        'double stn2::y', at offset 64 (in bits) at test-leaf-redundant-v1.c:9:1
 
-  [C] 'function void fn3(sto1*)' at test-leaf3-v1.c:16:1 has some sub-type changes:
+  [C] 'function void fn3(sto1*)' at test-leaf-redundant-v1.c:18:1 has some sub-type changes:
     parameter 1 of type 'sto1*' changed:
       pointer type changed from: 'sto1*' to: 'stn1*'
 
-  [C] 'function void fn4(sto2*)' at test-leaf3-v1.c:19:1 has some sub-type changes:
+  [C] 'function void fn4(sto2*)' at test-leaf-redundant-v1.c:21:1 has some sub-type changes:
     parameter 1 of type 'sto2*' changed:
       pointer type changed from: 'sto2*' to: 'stn2*'
 

tests/data/test-abidiff-exit/test-leaf-redundant-v0.c

@@ -1,3 +1,4 @@
+// See comments in -v1.c file.
 struct sto1 {
   int x;
 };

tests/data/test-abidiff-exit/test-leaf-redundant-v1.c

@@ -1,3 +1,5 @@
+// Ensure that --redundant is indeed implied by --leaf-changes-only mode and
+// that all the changed functions get complete reports.
 struct stn1 {
   int x;
 };
@@ -7,14 +9,14 @@ struct stn2 {
   double y;
 };
 
-void fn1(struct stn1 s) {
+void fn1(struct stn1 s) {  // was sto1
 }
 
-void fn2(struct stn2 s) {
+void fn2(struct stn2 s) {  // was sto2
 }
 
-void fn3(struct stn1* s) {
+void fn3(struct stn1* s) {  // was sto1
 }
 
-void fn4(struct stn2* s) {
+void fn4(struct stn2* s) {  // was sto2
 }

tests/data/test-abidiff-exit/test-leaf-stats-v0.cc

@@ -1,3 +1,4 @@
+// See comments in -v1.c file.
 int changed_var = 0;
 
 int changed_fun() {

tests/data/test-abidiff-exit/test-leaf-stats-v1.cc

@@ -1,5 +1,7 @@
-long changed_var = 0;
+// Test to ensure changed variables and functions are accounted for correctly in
+// --leaf-changes-only mode.
+long changed_var = 0;  // was int
 
-long changed_fun() {
+long changed_fun() {  // was int
   return 0;
 }