From d90ff8c74e10710f2648a2c49a57cfdb27902d17 Mon Sep 17 00:00:00 2001
From: Russell Taylor <taylorrj@ornl.gov>
Date: Wed, 7 Aug 2013 13:31:48 -0400
Subject: [PATCH] Re #7692. Add comments stating where helpers can & can't be
 used.

The test helpers should not be used in a way that breaks our package
dependency hierarchy, but this has been happening on occasion.
These comments give guidance on that and will hopefully be spotted
when someone is about to do something they shouldn't!
---
 .../BinaryOperationMDTestHelper.h             |  5 ++++
 .../MantidTestHelpers/BoxControllerDummyIO.h  | 10 ++++++-
 .../ComponentCreationHelper.h                 |  8 ++++++
 .../inc/MantidTestHelpers/FacilityHelper.h    |  5 ++++
 .../inc/MantidTestHelpers/FakeGmockObjects.h  | 26 ++++++-------------
 .../inc/MantidTestHelpers/FakeObjects.h       |  8 ++++++
 .../MantidTestHelpers/MDEventsTestHelper.h    |  6 +++++
 .../SANSInstrumentCreationHelper.h            |  7 +++++
 .../WorkspaceCreationHelper.h                 |  8 ++++++
 .../src/BinaryOperationMDTestHelper.cpp       |  6 ++++-
 .../TestHelpers/src/BoxControllerDummyIO.cpp  | 10 ++++++-
 .../src/ComponentCreationHelper.cpp           |  8 ++++++
 .../TestHelpers/src/MDEventsTestHelper.cpp    |  7 +++++
 .../src/SANSInstrumentCreationHelper.cpp      |  7 +++++
 .../src/WorkspaceCreationHelper.cpp           |  8 ++++++
 15 files changed, 108 insertions(+), 21 deletions(-)

diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/BinaryOperationMDTestHelper.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/BinaryOperationMDTestHelper.h
index c01af41235bd..557f2333a4d1 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/BinaryOperationMDTestHelper.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/BinaryOperationMDTestHelper.h
@@ -1,3 +1,8 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This header MAY ONLY be included from a test in the MDAlgorithms package.
+ *********************************************************************************/
 #ifndef MANTID_MDALGORITHMS_BINARYOPERATIONMDTESTHELPER_H_
 #define MANTID_MDALGORITHMS_BINARYOPERATIONMDTESTHELPER_H_
 
diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/BoxControllerDummyIO.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/BoxControllerDummyIO.h
index b875fdb4fc06..807afb0c2814 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/BoxControllerDummyIO.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/BoxControllerDummyIO.h
@@ -1,3 +1,11 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This header MAY NOT be included in any test from a package below API
+ *    (e.g. Kernel, Geometry).
+ *  Conversely, this file MAY NOT be modified to use anything from a package higher
+ *  than API (e.g. any algorithm or concrete workspace), even if via the factory.
+ *********************************************************************************/
 #ifndef MANTID_TESTHELPERS_BOXCONTROLLER_DUMMUY_IO_H
 #define MANTID_TESTHELPERS_BOXCONTROLLER_DUMMUY_IO_H
 
@@ -100,4 +108,4 @@ namespace MantidTestHelpers
     };
 
 }
-#endif
\ No newline at end of file
+#endif
diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/ComponentCreationHelper.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/ComponentCreationHelper.h
index 95899c8e0f4a..1fc15c83b136 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/ComponentCreationHelper.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/ComponentCreationHelper.h
@@ -1,3 +1,11 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This header MAY NOT be included in any test from a package below Geometry
+ *    (e.g. Kernel).
+ *  Conversely, this file (and its cpp) MAY NOT be modified to use anything from a
+ *  package higher than Geometry (e.g. API, DataObjects, ...)
+ *********************************************************************************/
 #ifndef COMPONENTCREATIONHELPER_H_
 #define COMPONENTCREATIONHELPER_H_
 
diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FacilityHelper.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FacilityHelper.h
index 3b1f10ab5f70..b045f0705794 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FacilityHelper.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FacilityHelper.h
@@ -1,3 +1,8 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This file MAY NOT be modified to use anything from a package other than Kernel.
+ *********************************************************************************/
 #ifndef TESTHELPERS_FACILITYHELPER_H_
 #define TESTHELPERS_FACILITYHELPER_H_
 
diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FakeGmockObjects.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FakeGmockObjects.h
index 3df1144d4452..51ae312a5f58 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FakeGmockObjects.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FakeGmockObjects.h
@@ -1,27 +1,17 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This header MAY NOT be included in any test from a package below Geometry
+ *    (i.e. Kernel).
+ *  Conversely, this file MAY NOT be modified to use anything from a package higher
+ *  than API (e.g. any algorithm or concrete workspace), even if via the factory.
+ *********************************************************************************/
 #ifndef FAKEGMOCKOBJECTS_H_
 #define FAKEGMOCKOBJECTS_H_
 
-/*
- * FakeObjects.h: Fake Tester objects for APITest
- *
- *  Created on: Jul 5, 2011
- *      Author: Janik Zikovsky
- */
-
-#include "MantidAPI/ISpectrum.h"
-#include "MantidAPI/MatrixWorkspace.h"
-#include "MantidKernel/cow_ptr.h"
-#include "MantidAPI/NumericAxis.h"
-#include "MantidGeometry/Instrument.h"
-#include "MantidGeometry/Instrument/DetectorGroup.h"
 #include "MantidGeometry/Instrument/INearestNeighboursFactory.h"
 #include "gmock/gmock.h"
-#include <iostream>
-#include <fstream>
-#include <map>
 
-using namespace Mantid::API;
-using namespace Mantid::Kernel;
 using namespace Mantid;
 
 
diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FakeObjects.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FakeObjects.h
index 6256d8d631d9..e02d19f6a907 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FakeObjects.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/FakeObjects.h
@@ -1,3 +1,11 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This header MAY NOT be included in any test from a package below API
+ *    (e.g. Kernel, Geometry).
+ *  Conversely, this file MAY NOT be modified to use anything from a package higher
+ *  than API (e.g. any algorithm or concrete workspace), even if via the factory.
+ *********************************************************************************/
 #ifndef FAKEOBJECTS_H_
 #define FAKEOBJECTS_H_
 
diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/MDEventsTestHelper.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/MDEventsTestHelper.h
index 452442908dea..1bcc78816a8e 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/MDEventsTestHelper.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/MDEventsTestHelper.h
@@ -1,3 +1,9 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This header MAY NOT be included in any test from a package below the level of
+ *  MDEvents (e.g. Kernel, Geometry, API, DataObjects).
+ *********************************************************************************/
 #ifndef MDEVENTSTEST_HELPER_H
 #define MDEVENTSTEST_HELPER_H
 
diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/SANSInstrumentCreationHelper.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/SANSInstrumentCreationHelper.h
index 2535744a96f7..09d78f68c791 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/SANSInstrumentCreationHelper.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/SANSInstrumentCreationHelper.h
@@ -1,3 +1,10 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This header MAY NOT be included in any test from a package below the level of
+ *  DataHandling (e.g. Kernel, Geometry, API, DataObjects).
+ *  I.e. It can only be used by plugin/algorithm-level packages (e.g. DataHandling)
+ *********************************************************************************/
 #ifndef SANSINSTRUMENTCREATIONHELPER_H_
 #define SANSINSTRUMENTCREATIONHELPER_H_
 
diff --git a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/WorkspaceCreationHelper.h b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/WorkspaceCreationHelper.h
index 617f7219e92f..d59aee9ed81d 100644
--- a/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/WorkspaceCreationHelper.h
+++ b/Code/Mantid/Framework/TestHelpers/inc/MantidTestHelpers/WorkspaceCreationHelper.h
@@ -1,3 +1,11 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This header MAY NOT be included in any test from a package below DataObjects
+ *    (e.g. Kernel, Geometry, API).
+ *  Conversely, this file (and its cpp) MAY NOT be modified to use anything from a
+ *  package higher than DataObjects (e.g. any algorithm), even if via the factory.
+ *********************************************************************************/
 #ifndef WORKSPACECREATIONHELPER_H_
 #define WORKSPACECREATIONHELPER_H_
 //------------------------------------------------------------------------------
diff --git a/Code/Mantid/Framework/TestHelpers/src/BinaryOperationMDTestHelper.cpp b/Code/Mantid/Framework/TestHelpers/src/BinaryOperationMDTestHelper.cpp
index 04e432409af7..d2cf38738342 100644
--- a/Code/Mantid/Framework/TestHelpers/src/BinaryOperationMDTestHelper.cpp
+++ b/Code/Mantid/Framework/TestHelpers/src/BinaryOperationMDTestHelper.cpp
@@ -1,4 +1,8 @@
-
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  These functions MAY ONLY be used in a test in the MDAlgorithms package.
+ *********************************************************************************/
 #include "MantidAPI/IMDEventWorkspace.h"
 #include "MantidDataObjects/WorkspaceSingleValue.h"
 #include "MantidKernel/System.h"
diff --git a/Code/Mantid/Framework/TestHelpers/src/BoxControllerDummyIO.cpp b/Code/Mantid/Framework/TestHelpers/src/BoxControllerDummyIO.cpp
index 2a0e1def4b53..cc1338351e7e 100644
--- a/Code/Mantid/Framework/TestHelpers/src/BoxControllerDummyIO.cpp
+++ b/Code/Mantid/Framework/TestHelpers/src/BoxControllerDummyIO.cpp
@@ -1,3 +1,11 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This collection of functions MAY NOT be used in any test from a package below
+ *  API (e.g. Kernel, Geometry).
+ *  Conversely, this file MAY NOT be modified to use anything from a package higher
+ *  than API (e.g. any algorithm or concrete workspace), even if via the factory.
+ *********************************************************************************/
 #include "MantidTestHelpers/BoxControllerDummyIO.h"
 #include "MantidKernel/Exception.h"
 
@@ -160,4 +168,4 @@ namespace MantidTestHelpers
       this->closeFile();
   }
 
-}
\ No newline at end of file
+}
diff --git a/Code/Mantid/Framework/TestHelpers/src/ComponentCreationHelper.cpp b/Code/Mantid/Framework/TestHelpers/src/ComponentCreationHelper.cpp
index 2f3ffe434123..1aa49e33f19e 100644
--- a/Code/Mantid/Framework/TestHelpers/src/ComponentCreationHelper.cpp
+++ b/Code/Mantid/Framework/TestHelpers/src/ComponentCreationHelper.cpp
@@ -1,3 +1,11 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This collection of functions MAY NOT be used in any test from a package below
+ *  Geometry (e.g. Kernel).
+ *  Conversely, this file MAY NOT be modified to use anything from a package
+ *  higher than Geometry (e.g. API, DataObjects, ...)
+ *********************************************************************************/
 //------------------------------------------------------------------------------
 // Includes
 //------------------------------------------------------------------------------
diff --git a/Code/Mantid/Framework/TestHelpers/src/MDEventsTestHelper.cpp b/Code/Mantid/Framework/TestHelpers/src/MDEventsTestHelper.cpp
index d8d125c8730d..a5bd06924e35 100644
--- a/Code/Mantid/Framework/TestHelpers/src/MDEventsTestHelper.cpp
+++ b/Code/Mantid/Framework/TestHelpers/src/MDEventsTestHelper.cpp
@@ -1,3 +1,10 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This collection of functions MAY NOT be used in any test from a package below
+ *  the level of MDEvents (e.g. Kernel, Geometry, API, DataObjects).
+ *********************************************************************************/
+
 #include "MantidAPI/MatrixWorkspace.h"
 #include "MantidDataHandling/LoadInstrument.h"
 #include "MantidDataObjects/EventWorkspace.h"
diff --git a/Code/Mantid/Framework/TestHelpers/src/SANSInstrumentCreationHelper.cpp b/Code/Mantid/Framework/TestHelpers/src/SANSInstrumentCreationHelper.cpp
index 542ca61aca54..bae68c4ccd49 100644
--- a/Code/Mantid/Framework/TestHelpers/src/SANSInstrumentCreationHelper.cpp
+++ b/Code/Mantid/Framework/TestHelpers/src/SANSInstrumentCreationHelper.cpp
@@ -1,3 +1,10 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This collection of functions MAY NOT be used in any test from a package below
+ *  the level of DataHandling (e.g. Kernel, Geometry, API, DataObjects).
+ *  I.e. It can only be used by plugin/algorithm-level packages (e.g. DataHandling)
+ *********************************************************************************/
 #include "MantidTestHelpers/SANSInstrumentCreationHelper.h"
 #include "MantidTestHelpers/WorkspaceCreationHelper.h"
 #include "MantidAPI/AnalysisDataService.h"
diff --git a/Code/Mantid/Framework/TestHelpers/src/WorkspaceCreationHelper.cpp b/Code/Mantid/Framework/TestHelpers/src/WorkspaceCreationHelper.cpp
index afe11e5e2fec..0639a060a5a3 100644
--- a/Code/Mantid/Framework/TestHelpers/src/WorkspaceCreationHelper.cpp
+++ b/Code/Mantid/Framework/TestHelpers/src/WorkspaceCreationHelper.cpp
@@ -1,3 +1,11 @@
+/*********************************************************************************
+ *  PLEASE READ THIS!!!!!!!
+ *
+ *  This collection of functions MAY NOT be used in any test from a package below
+ *  DataObjects (e.g. Kernel, Geometry, API).
+ *  Conversely, this file MAY NOT be modified to use anything from a package higher
+ *  than DataObjects (e.g. any algorithm), even if going via the factory.
+ *********************************************************************************/
 //------------------------------------------------------------------------------
 // Includes
 //------------------------------------------------------------------------------