From d5d00f3f7855d2dcf746eae76f2cc80005156cfa Mon Sep 17 00:00:00 2001
From: Attila Kovacs <attipaci@gmail.com>
Date: Mon, 11 Nov 2024 13:49:35 +0100
Subject: [PATCH] apidoc edits and site update

---
 CHANGELOG.md         |  2 +-
 LEGACY.md            |  2 +-
 src/naif.c           |  3 +++
 src/solsys-calceph.c | 16 +++++++++++++---
 src/solsys-cspice.c  | 24 ++++++++++++++++++++++--
 5 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 705f0a3a..5ee6e765 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-## [1.2.0-rc1] - 2024-11-11
+## [Unreleased]
 
 Changes expected for the next feature release, expected around 1 February 2025.
 
diff --git a/LEGACY.md b/LEGACY.md
index 6e796747..3987b9cd 100644
--- a/LEGACY.md
+++ b/LEGACY.md
@@ -1,4 +1,4 @@
-# SuperNOVAS: Astrometric Positions the Old Way
+# Astrometric Positions the Old Way
 
 As of version 1.1, the SuperNOVAS library offers a new, more versatile, more intuitive, and more efficient way to 
 calculate the astrometric positions (and velocities) of celestial sources, via observing frames (see `README.md`). 
diff --git a/src/naif.c b/src/naif.c
index cc816cfa..e86324a0 100644
--- a/src/naif.c
+++ b/src/naif.c
@@ -10,6 +10,9 @@
  *  this set (and no defined ID for EMB), thus for all other objects we'll assume and use NOVAS IDs that match NAIF.
  *
  * @since 1.2
+ *
+ * @sa solsys-calceph.c
+ * @sa solsys-cspice.c
  */
 
 #include <errno.h>
diff --git a/src/solsys-calceph.c b/src/solsys-calceph.c
index ae763bef..a3c26667 100644
--- a/src/solsys-calceph.c
+++ b/src/solsys-calceph.c
@@ -4,11 +4,21 @@
  * @author A. Kovacs
  * @since 1.2
  *
- *  SuperNOVAS major planet ephemeris lookup implementation via the CALCEPH C library
- *  See https://calceph.imcce.fr/docs/4.0.0/html/c/
+ *  SuperNOVAS Solar-system ephemeris lookup implementation via the CALCEPH C library.
  *
- *  CALCEPH source code is at https://gitlab.obspm.fr/imcce_calceph/calceph
+ *  This is an optional component of SuperNOVAS, which interfaces to the CALCEPH C library.
+ *  As such, you may need the CALCEPH runtime libraries in an accessible location (such
+ *  as in `/usr/lib`) to use, and you will need development files (C headers and unversioned
+ *  libraries) to build. Thus, this module is compiled only if `CALCEPH_SUPPORT` is set
+ *  to 1 prior to the build.
  *
+ * REFERENCES:
+ * <ol>
+ *  <li>CALCEPH is at https://calceph.imcce.fr/docs/4.0.0/html/c/</li>
+ *  <li>CALCEPH source code is at https://gitlab.obspm.fr/imcce_calceph/calceph</li>
+ * </ol>
+ *
+ * @sa solsys-cspice.c
  */
 
 #include <string.h>
diff --git a/src/solsys-cspice.c b/src/solsys-cspice.c
index a694cbb4..6f197c53 100644
--- a/src/solsys-cspice.c
+++ b/src/solsys-cspice.c
@@ -4,9 +4,25 @@
  * @author A. Kovacs
  * @since 1.2
  *
- *  SuperNOVAS major planet ephemeris lookup implementation via the NAIF CSPICE library
- *  See https://naif.jpl.nasa.gov/naif/toolkit.html
+ *  SuperNOVAS Solar-system ephemeris lookup implementation via the NAIF CSPICE library.
  *
+ *  This is an optional component of SuperNOVAS, which interfaces to the NAIF CSPICE Toolkit.
+ *  As such, you may need the CSPICE runtime libraries in an accessible location (such
+ *  as in `/usr/lib`), and you will need development files (C headers under a `cspice/`
+ *  sub-folder, such as in `/usr/include/cspice/`; and unversioned libraries) to build. Thus,
+ *  this module is compiled only if `CSPICE_SUPPORT` is set to 1 prior to the build.
+ *
+ *  Before building SuperNOVAS against CSPICE, you might want to check out the
+ *  `Smithsonian/cspice-sharedlib` repository on Github to facilitate the building of CSPICE
+ *  as a shared library instead of the static library built by the uptream distribution.
+ *
+ *  REFERENCES:
+ *  <ol>
+ *  <li>The NAIF CSPICE Toolkit: https://naif.jpl.nasa.gov/naif/toolkit.html</li>
+ *  <li>the Smithsonian/cspice-sharedlib repository: https://github.com/Smithsonian/cspice-sharedlib</li>
+ *  </ol>
+ *
+ * @sa solsys-calceph.c
  */
 
 #include <string.h>
@@ -103,6 +119,7 @@ static int get_cspice_error(char *msg, int len) {
  *                      EINVAL).
  *
  * @sa cspice_remove_kernel()
+ * @sa novas_use_cspice()
  *
  * @author Attila Kovacs
  * @since 1.2
@@ -460,6 +477,7 @@ static int novas_cspice(const char *name, long id, double jd_tdb_high, double jd
  *
  * @sa novas_use_cspice_planets()
  * @sa novas_use_cspice()
+ * @sa cspice_add_kernel()
  * @sa set_ephem_provider()
  *
  * @author Attila Kovacs
@@ -483,6 +501,7 @@ int novas_use_cspice_ephem() {
  *
  * @sa novas_use_cspice_ephem()
  * @sa novas_use_cspice()
+ * @sa cspice_add_kernel()
  * @sa set_planet_provider()
  * @sa set_planet_provider_hp()
  *
@@ -508,6 +527,7 @@ int novas_use_cspice_planets() {
  *
  * @sa novas_use_cspice_planets()
  * @sa novas_use_cspice_ephem()
+ * @sa cspice_add_kernel()
  *
  * @author Attila Kovacs
  * @since 1.2