expand/clarify comments -- no changes to executable code

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/AHFinderDirect/trunk@1315 f88db872-0e4f-0410-b76b-b9085cfa78c5

1 files changed, 25 insertions, 11 deletions

diff --git a/src/driver/aliased_functions.cc b/src/driver/aliased_functions.cc
index 2b21d81..b647198 100644
--- a/src/driver/aliased_functions.cc
+++ b/src/driver/aliased_functions.cc
@@ -60,6 +60,11 @@ extern struct state state;
 // This function is called (via the Cactus flesh function-aliasing mechanism)
 // by other thorns to find out our local coordinate origin for a given AH.
 //
+// Arguments:
+// horizon_number = (in) The horizon to inquire about; must be in the range
+//			 1 to N_horizons inclusive.
+// *origin_[xyz]_ptr = (out) The local coordinate origin is stored here.
+//
 // Results:
 // This function returns 0 for ok, or -1 if the horizon number is invalid.
 //
@@ -100,6 +105,10 @@ return 0;						// *** NORMAL RETURN ***
 // by other thorns to query whether or not the specified horizon was found
 // the last time we searched for it.
 //
+// Arguments:
+// horizon_number = (in) The horizon to inquire about; must be in the range
+//			 1 to N_horizons inclusive.
+//
 // Results:
 // This function returns
 //  1 if the horizon was found
@@ -134,22 +143,27 @@ return AH_data.found_flag ? 1 : 0;
 // by other thorns to find out a given AH's radius in the direction from
 // its local coordinate origin to a given (x,y,z) coordinate or coordinates.
 //
-// FIXME:
-// The current implementation is quite inefficient: it does a full 2-D
-// interpolation (to find the horizon radius) for each of the xyz points.
-// It would be more efficient to batch the interpolations.
-//
 // Arguments:
-// horizon_number = must be in the range 1 to N_horizons
-// N_points = should be >= 0
-// x[], y[], z[] = these give the (x,y,z) coordinates
-// radius[] = this is set to the horizon radius values (Euclidean distance
-//	      from the local coordinate origin), or to all -1.0 if we didn't
-//	      find this horizon the last time we looked for it
+// horizon_number = (in) The horizon to inquire about; must be in the range
+//			 1 to N_horizons inclusive.
+// N_points = (in) Number of (x,y,z) coordinate tuples (should be >= 0).
+// x[], y[], z[] = (in) These arrays give the (x,y,z) coordinates.
+// radius[] = (out) This array is set to the horizon radius values
+//		    (Euclidean distances from the local coordinate origin),
+//		    or to all -1.0 if we didn't find this horizon the
+//		    last time we looked for it.
 //
 // Results:
 // This function returns 0 for ok, or -1 if the horizon number is invalid.
 //
+// FIXME:
+// * The current implementation is quite inefficient: it does a full 2-D
+//   interpolation (to find the horizon radius) for each of the xyz points.
+//   It would be more efficient to batch the interpolations.
+// * If an (x,y,z) coordinate tuple coincides with this horizon's local
+//   coordinate origin, we return the dummy radius 1.0.  It would be
+//   better to return -1.0.
+//
 extern "C"
   CCTK_INT AHFinderDirect_radius_in_direction
     (CCTK_INT horizon_number,