solsys-ephem error handling, many doc corrections and edits

CHANGELOG.md

@@ -11,7 +11,7 @@ This is the initial release of the SuperNOVAS library.
    had an incorrect unit cast. This is a known issue of NOVAS C 3.1.
 
  - Fixes the [ephem_close bug](https://aa.usno.navy.mil/software/novas_faq), whereby `ephem_close()` in 
-   `ephem_manager.c` did not reset the `EPHFILE` pointer to NULL. This is a known issue of NOVAS C 3.1.
+   `eph_manager.c` did not reset the `EPHFILE` pointer to NULL. This is a known issue of NOVAS C 3.1.
 
  - Fixes antedating velocities and distances for light travel time in `ephemeris()`. When getting positions and 
    velocities for Solar-system sources, it is important to use the values from the time light originated from the 
@@ -33,7 +33,7 @@ This is the initial release of the SuperNOVAS library.
    `equinox` argument was changing from 1 to 0, and back to 1 again with the date being held the same. This affected 
    routines downstream also, such as `sidereal_time()`.
 
- - Fixes accuracy switching bug in `cio_basis()`, `cio_location()`, `ecl2equ`, `equ2ecl_vec()`, `ecl2equ_vec()`, 
+ - Fixes accuracy switching bug in `cio_basis()`, `cio_location()`, `ecl2equ()`, `equ2ecl_vec()`, `ecl2equ_vec()`, 
    `geo_posvel()`,  `place()`, and `sidereal_time()`. All these functions returned a cached value for the other 
    accuracy if the other input parameters are the same as a prior call, except the accuracy. 
 
@@ -43,7 +43,7 @@ This is the initial release of the SuperNOVAS library.
  - Fixes `aberration()` returning NAN vectors if the `ve` argument is 0. It now returns the unmodified input vector 
    appropriately instead.
 
- - Fixes unpopulated `az` output value in `equ2hor` at zenith. While any azimuth is acceptable really, it results in 
+ - Fixes unpopulated `az` output value in `equ2hor()` at zenith. While any azimuth is acceptable really, it results in 
    irreproducible behavior. Hence, we set az to 0.0 for zenith to be consistent.
 
  - Fixes potential string overflows and eliminates associated compiler warnings.
@@ -70,8 +70,8 @@ This is the initial release of the SuperNOVAS library.
 
  - New runtime configurability:
 
-   * The planet position calculator function used by `ephemeris` can be set at runtime via `set_planet_provider()`, and
-     `set_planet_provider_hp` (for high precision calculations). Similarly, if `planet_ephem_provider()` or 
+   * The planet position calculator function used by `ephemeris()` can be set at runtime via `set_planet_provider()`, 
+     and `set_planet_provider_hp()` (for high precision calculations). Similarly, if `planet_ephem_provider()` or 
      `planet_ephem_provider_hp()` (defined in `solsys-ephem.c`) are set as the planet calculator functions, then 
      `set_ephem_provider()` can set the user-specified function to use with these to actually read ephemeris data
      (e.g. from a JPL ephemeris file).
@@ -116,7 +116,7 @@ This is the initial release of the SuperNOVAS library.
  - Co-existing `solarsystem()` variants. It is possible to use the different `solarsystem()` implementations 
    provided by `solsys1.c`, `solsys2.c`, `solsys3.c` and/or `solsys-ephem.c` side-by-side, as they define their
    functionalities with distinct, non-conflicting names, e.g. `earth_sun_calc()` vs `planet_jplint()` vs
-   `planet_ephem_manager()` vs `planet_ephem_provider()`. See the section on 
+   `planet_eph_manager` vs `planet_ephem_provider()`. See the section on 
    [Building and installation](#installation) further above on including a selection of these in your library 
    build.)
 
@@ -156,7 +156,7 @@ This is the initial release of the SuperNOVAS library.
    This eliminates the need to declare dummy variables in your application code for quantities you do not require.
 
  - All SuperNOVAS functions that take an input vector to produce an output vector allow the output vector argument
-   be the same as the input vector argument. For example, `frame_time(pos, J2000_TO_ICRS, pos)` using the same 
+   be the same as the input vector argument. For example, `frame_tie(pos, J2000_TO_ICRS, pos)` using the same 
    `pos` vector both as the input and the output. In this case the `pos` vector is modified in place by the call. 
    This can greatly simplify usage, and can eliminate extraneous declarations, when intermediates are not required.
 
@@ -170,7 +170,7 @@ This is the initial release of the SuperNOVAS library.
 
  - Object ID numbers are `long` instead of `short` to accommodate NAIF IDs, which require minimum 32-bit integers.
 
- - `cel2ter()` and `tel2cel()` can now process 'option'/'class' = 1 (`NOVAS_REFERENCE_CLASS`) regardless of the
+ - `cel2ter()` and `ter2cel()` can now process 'option'/'class' = 1 (`NOVAS_REFERENCE_CLASS`) regardless of the
    methodology (`EROT_ERA` or `EROT_GST`) used to input or output coordinates in GCRS.
 
  - Changed `make_object()` to retain the specified number argument (which can be different from the `starnumber` value

Makefile

@@ -33,7 +33,7 @@ coverage:
 	make -C test coverage
 
 .PHONY: all
-all: api solsys test coverage check
+all: api solsys obj/novascon.o test coverage check
 
 .PHONY: clean
 clean:

README.md

@@ -100,7 +100,7 @@ provided by SuperNOVAS over the upstream NOVAS C 3.1 code:
    had an incorrect unit cast. This is a known issue of NOVAS C 3.1.
 
  - Fixes the [ephem_close bug](https://aa.usno.navy.mil/software/novas_faq), whereby `ephem_close()` in 
-   `ephem_manager.c` did not reset the `EPHFILE` pointer to NULL. This is a known issue of NOVAS C 3.1.
+   `eph_manager.c` did not reset the `EPHFILE` pointer to NULL. This is a known issue of NOVAS C 3.1.
 
  - Fixes antedating velocities and distances for light travel time in `ephemeris()`. When getting positions and 
    velocities for Solar-system sources, it is important to use the values from the time light originated from the 
@@ -122,7 +122,7 @@ provided by SuperNOVAS over the upstream NOVAS C 3.1 code:
    `equinox` argument was changing from 1 to 0, and back to 1 again with the date being held the same. This affected 
    routines downstream also, such as `sidereal_time()`.
 
- - Fixes accuracy switching bug in `cio_basis()`, `cio_location()`, `ecl2equ`, `equ2ecl_vec()`, `ecl2equ_vec()`, 
+ - Fixes accuracy switching bug in `cio_basis()`, `cio_location()`, `ecl2equ()`, `equ2ecl_vec()`, `ecl2equ_vec()`, 
    `geo_posvel()`, `place()`, and `sidereal_time()`. All these functions returned a cached value for the other 
    accuracy if the other input parameters are the same as a prior call, except the accuracy. 
 
@@ -132,7 +132,7 @@ provided by SuperNOVAS over the upstream NOVAS C 3.1 code:
  - Fixes `aberration()` returning NaN vectors if the `ve` argument is 0. It now returns the unmodified input vector 
    appropriately instead.
 
- - Fixes unpopulated `az` output value in `equ2hor` at zenith. While any azimuth is acceptable really, it results in 
+ - Fixes unpopulated `az` output value in `equ2hor()` at zenith. While any azimuth is acceptable really, it results in 
    irreproducible behavior. Hence, we set az to 0.0 for zenith to be consistent.
 
  - Fixes potential string overflows and eliminates associated compiler warnings.
@@ -576,8 +576,8 @@ before that level of accuracy is reached.
 
  - New runtime configuration:
 
-   * The planet position calculator function used by `ephemeris` can be set at runtime via `set_planet_provider()`, 
-     and `set_planet_provider_hp` (for high precision calculations). Similarly, if `planet_ephem_provider()` or 
+   * The planet position calculator function used by `ephemeris()` can be set at runtime via `set_planet_provider()`, 
+     and `set_planet_provider_hp()` (for high precision calculations). Similarly, if `planet_ephem_provider()` or 
      `planet_ephem_provider_hp()` (defined in `solsys-ephem.c`) are set as the planet calculator functions, then 
      `set_ephem_provider()` can set the user-specified function to use with these to actually read ephemeris data
      (e.g. from a JPL `.bsp` file).
@@ -622,7 +622,7 @@ before that level of accuracy is reached.
  - Co-existing `solarsystem()` variants. It is possible to use the different `solarsystem()` implementations 
    provided by `solsys1.c`, `solsys2.c`, `solsys3.c` and/or `solsys-ephem.c` side-by-side, as they define their
    functionalities with distinct, non-conflicting names, e.g. `earth_sun_calc()` vs `planet_jplint()` vs
-   `planet_ephem_manager()` vs `planet_ephem_provider()`. See the section on 
+   `planet_eph_manager` vs `planet_ephem_provider()`. See the section on 
    [Building and installation](#installation) further above on including a selection of these in your library 
    build.)
 
@@ -661,7 +661,7 @@ before that level of accuracy is reached.
    should not be used as if they were valid. (No more sneaky silent failures.)
 
  - All SuperNOVAS functions that take an input vector to produce an output vector allow the output vector argument
-   be the same as the input vector argument. For example, `frame_time(pos, J2000_TO_ICRS, pos)` using the same 
+   be the same as the input vector argument. For example, `frame_tie(pos, J2000_TO_ICRS, pos)` using the same 
    `pos` vector both as the input and the output. In this case the `pos` vector is modified in place by the call. 
    This can greatly simplify usage, and eliminate extraneous declarations, when intermediates are not required.
 
@@ -674,7 +674,7 @@ before that level of accuracy is reached.
 
  - `cio_location()` will always return a valid value as long as neither output pointer arguments is NULL.
 
- - `cel2ter()` and `tel2cel()` can now process 'option'/'class' = 1 (`NOVAS_REFERENCE_CLASS`) regardless of the
+ - `cel2ter()` and `ter2cel()` can now process 'option'/'class' = 1 (`NOVAS_REFERENCE_CLASS`) regardless of the
    methodology (`EROT_ERA` or `EROT_GST`) used to input or output coordinates in GCRS.
 
  - More efficient paging (cache management) for `cio_array()`, including I/O error checking.
@@ -753,13 +753,14 @@ provided you compiled SuperNOVAS with `BUILTIN_SOLSYS_EPHEM = 1` (in `config.mk`
 
 If you only need support for major planets, you may be able to use one of the modules included in the SuperNOVAS
 distribution. The modules `solsys1.c` and `solsys2.c` provide built-in support to older JPL ephemerides (DE200 to DE421), 
-either via the `ephem_manager()` interface of `solsys1.c` or via the `jplint_()` interface of `solsys2.c`.
+either via the `eph_manager` interface of `solsys1.c` or via the FORTRAN `jplint_()` / `jplihp_()` interface of 
+`solsys2.c`.
 
 #### 2.1. Planets via `eph_manager`
 
 To use the `eph_manager` interface for planet 1997 JPL planet ephemeris (DE200 through DE421), you must either build 
 superNOVAS with `BUILTIN_SOLSYS1 = 1` in `config.mk`, or else link your application with `solsys1.c` and 
-`ephem_manager.c` from SuperNOVAS explicitly. If you want `eph_manager` to be your default ephemeris provider (the old 
+`eph_manager.c` from SuperNOVAS explicitly. If you want `eph_manager` to be your default ephemeris provider (the old 
 way) you might also want to set `DEFAULT_SOLSYS = 1` in `config.mk`. Otherwise, your application should set 
 `eph_manager` as your planetary ephemeris provider at runtime via:
 
@@ -783,7 +784,7 @@ And, when you are done using the ephemeris file, you should close it with
  ephem_close();
 ```
 
-Note, that at any given time `eph_manager()` can have only one ephemeris data file opened. You cannot use it to 
+Note, that at any given time `eph_manager` can have only one ephemeris data file opened. You cannot use it to 
 retrieve data from multiple ephemeris input files at the same time. (But you can with the CSPICE toolkit, which you 
 can integrate as discussed further above!)
 
@@ -792,11 +793,11 @@ That's all, except the warning that this method will not work with newer JPL eph
 
 #### 2.b. Planets via JPL's `pleph` FORTRAN interface
 
-To use the `jplint_` interface for planet ephemerides, you must either build superNOVAS with `BUILTIN_SOLSYS2 = 1` in 
-`config.mk`, or else link your application with `solsys2.c` and `jplint.f` from SuperNOVAS explicitly (as well as 
-`pleph.f` etc. from the JPL library). If you want the JPL `pleph`-based interface  to be your default ephemeris provider 
-(the old way) you might also want to set `DEFAULT_SOLSYS = 2` in `config.mk`. Otherwise, your application should set 
-your planetary ephemeris provider at runtime via:
+To use the `jplint_` / `jplihp_()` interface for planet ephemerides, you must either build superNOVAS with 
+`BUILTIN_SOLSYS2 = 1` in `config.mk`, or else link your application with `solsys2.c` and `jplint.f` from SuperNOVAS 
+explicitly (as well as `pleph.f` etc. from the JPL library). If you want the JPL `pleph`-based interface  to be your 
+default ephemeris provider (the old way) you might also want to set `DEFAULT_SOLSYS = 2` in `config.mk`. Otherwise, 
+your application should set your planetary ephemeris provider at runtime via:
 
 ```c
  set_planet_provider(planet_jplint);

include/solarsystem.h

@@ -281,27 +281,34 @@ short planet_jplint(double jd_tdb, enum novas_planet body, enum novas_origin ori
 
 short planet_jplint_hp(const double jd_tdb[2], enum novas_planet body, enum novas_origin origin, double *position, double *velocity);
 
+/// \cond PRIVATE
+
+#  ifdef __NOVAS_INTERNAL_API__
+
 /**
- * The function to use to provide planet epehemeris data.
+ * The function to use to provide planet ephemeris data.
  *
- * @sa novas_set_planet_provider()
- * @sa default_planet_provider_hp
+ * @sa set_planet_provider()
+ * @sa planet_call_hp
  *
  * @since 1.0
  * @author Attila Kovacs
  */
 extern novas_planet_provider planet_call;
 
 /**
- * The default 'fallback' function to use to provide high-precision planet epehemeris data.
+ * The default 'fallback' function to use to provide high-precision planet ephemeris data.
  *
- * @sa novas_set_planet_provider_hp()
- * @sa default_planet
+ * @sa set_planet_provider_hp()
+ * @sa planet_call
  *
  * @since 1.0
  * @author Attila Kovacs
  */
 extern novas_planet_provider_hp planet_call_hp;
 
+#  endif /* __NOVAS_INTERNAL_API__ */
+
+/// \endcond
 
 #endif

src/eph_manager.c

@@ -3,9 +3,13 @@
  *
  * @author G. Kaplan and A. Kovacs
  *
- *  SuperNOVAS planetary ephemeris manager for the planet_eph_manager() and planet_eph_manager_hp()
+ *  SuperNOVAS planetary ephemeris manager for the planet_eph_manager and planet_eph_manager_hp()
  *  functions.
  *
+ *  This module exposes a lot of its own internal state variables globally. You probably should
+ *  not access them from outside this module, but they are kept ad globals to ensure compatibility
+ *  with existing NOVAS C applications that do tinker with those values.
+ *
  *  Based on the NOVAS C Edition, Version 3.1,  U. S. Naval Observatory
  *  Astronomical Applications Dept.
  *  Washington, DC
@@ -22,16 +26,15 @@
 
 #include "eph_manager.h"
 
+/// \cond PRIVATE
 #define __NOVAS_INTERNAL_API__      ///< Use definitions meant for internal use by SuperNOVAS only
+/// \endcond
+
 #include "novas.h"
 
-
-/**
- * Flag that defines physical units of the output states. 1: km and km/sec; 0: AU and AU/day.
- *
- * Default value is 0 (KM determines time unit for nutations. Angle unit is always radians.)
- */
-short KM;
+/// Flag that defines physical units of the output states. 1: km and km/sec; 0: AU and AU/day.
+/// Its default value is 0 (KM determines time unit for nutations. Angle unit is always radians.)
+short KM;           ///< Flag that defines physical units of the output states.
 
 // IPT and LPT defined as int to support 64 bit systems.
 int IPT[3][12];     ///< (<i>for internal use</i>)
@@ -50,8 +53,8 @@ double TWOT;        ///< (<i>for internal use</i>)
 double EM_RATIO;    ///< (<i>for internal use</i>)
 double *BUFFER;     ///< (<i>for internal use</i>) Array containing Chebyshev coefficients of position.
 
-/** The currently opened JPL DE planetary ephemeris file */
-FILE *EPHFILE = NULL;
+
+FILE *EPHFILE = NULL;     ///< (<i>for internal use</i>) The currently open JPL DE planetary ephemeris file
 
 /**
  * This function opens a JPL planetary ephemeris file and