Index: trunk/Ohana/src/libohana/include/ohana.h
===================================================================
--- trunk/Ohana/src/libohana/include/ohana.h	(revision 28645)
+++ trunk/Ohana/src/libohana/include/ohana.h	(revision 29537)
@@ -94,7 +94,20 @@
 };
 
-/* note: in the Ohana tree, the byte order is determined by the ARCH variable
-   if you have a small endian machine that is not listed here, the test
-   program 'typestest' should fail */
+/* Some notes on the Ohana BYTE_SWAP macros:
+
+   1) BYTE_SWAP is set in this file based on the environment variable 'ARCH', which is in turn
+   set by the psconfig system (or is set manually by the builder).  
+
+   2) BYTE_SWAP is only used when building the Ohana tree: code which links against Ohana
+   (eg, libkapa or others) does not need to have this value correctly set.
+   
+   3) the libohana build tests for the validity of the BYTE_SWAP choice by running the test
+   program 'typestest' and raising an error if the tests fail.
+
+   4) if your build fails due to the typestest program, check your value of 'ARCH' and if
+   necessary add it to the list below.
+
+*/
+
 # ifndef BYTE_SWAP
 # ifdef linux
@@ -117,7 +130,10 @@
 # define BYTE_SWAP
 # endif
-# else
+# endif /* BYTE_SWAP */
+
+/* other Ohana components use these two values to check that ohana.h was correctly included */
+# ifndef BYTE_SWAP
 # define NOT_BYTE_SWAP
-# endif /* BYTE_SWAP */
+# endif
 
 # ifndef NAN