Move private headers to "internal", document that.

Author: tfry-git

Mozzi.h

@@ -0,0 +1,28 @@
+/*
+ * Mozzi.h
+ *
+ * Copyright 2023, Thomas Combriat and the Mozzi team
+ *
+ * This file is part of Mozzi.
+ *
+ * Mozzi is licensed under a Creative Commons
+ * Attribution-NonCommercial-ShareAlike 4.0 International License.
+ *
+ */
+
+/** @ingroup core 
+ * @file Mozzi.h
+ *
+ * This is the main include file in Mozzi. Almost all sketches using Mozzi will want to include this file @em exactly once.
+ *
+ * Should your sketch require \ref core Mozzi functions in more than one translation unit (i.e. you have more than one .cpp-file
+ * in your sketch itself), only *one* of these shall include this file, while any others shall include \ref MozziHeadersOnly instead.
+ * (Failing to heed this advice will lead to "duplicate definition" errors.)
+ */
+
+#ifndef MOZZI_H_
+#define MOZZI_H_
+
+#include "MozziGuts.h"
+
+#endif

MozziGuts.h

@@ -12,7 +12,14 @@
 #ifndef MOZZIGUTS_H_
 #define MOZZIGUTS_H_
 
- #include "Arduino.h"
+#include "Arduino.h"
+
+#include "MozziConfigValues.h"
+
+#if !(defined(MOZZI_H_) || defined(MOZZI_HEADERS_ONLY_H_))
+#warning Direct inclusion of MozziGuts.h is deprecated. Use Mozzi.h, instead, and read about porting to Mozzi 2.0
+#define MOZZI_COMPATIBILITY_LEVEL MOZZI_COMPATIBILITY_1_1
+#endif
 
 #include "hardware_defines.h"
 #include "mozzi_config.h"
@@ -82,7 +89,7 @@ forked version of Mozzi on github, so sound production can continue while
 reading sensors.
 
 As it is, stopMozzi restores all the Timers used by Mozzi to their previous
-settings. Another scenario which could be easily hacked in MozziGuts.cpp could
+settings. Another scenario which could be easily hacked in MozziGuts.hpp could
 involve individually saving and restoring particular Timer registers depending
 on which one(s) are required for other tasks.
 
@@ -173,8 +180,8 @@ is output, so the resolution is 1/AUDIO_RATE microseconds (61 microseconds when
 */
 unsigned long mozziMicros();
 
-#ifndef MOZZI_HEADER_ONLY
-#include "MozziGuts.hpp"
+#ifndef _MOZZI_HEADER_ONLY
+#include "internal/MozziGuts.hpp"
 #endif
 
 #endif /* MOZZIGUTS_H_ */

MozziHeadersOnly.h

@@ -0,0 +1,28 @@
+/*
+ * Mozzi.h
+ *
+ * Copyright 2023, Thomas Combriat and the Mozzi team
+ *
+ * This file is part of Mozzi.
+ *
+ * Mozzi is licensed under a Creative Commons
+ * Attribution-NonCommercial-ShareAlike 4.0 International License.
+ *
+ */
+
+/** @ingroup core 
+ * @file MozziHeadersOnly.h
+ *
+ * This file provides declarations of the \ref core Mozzi functions, but no implementation. Use this only, if you have more than one
+ * translation unit in your project (i.e. you have more than one .cpp-file in your sketch itself). Otherwise include \ref Mozzi.h, instead.
+ *
+ * (Failure to head this advice will lead to "symbol XY undefined" errors.).
+ */
+
+#ifndef MOZZI_HEADERS_ONLY_H_
+#define MOZZI_HEADERS_ONLY_H_
+
+#define _MOZZI_HEADER_ONLY
+#include "MozziGuts.h"
+
+#endif

Readme_Mozzi_2_0.md

@@ -28,11 +28,16 @@ all new
 general:
  - Added many config sanity checks. Some may be too strict, if so please mention
 
- Other removed stuff:
+Other removed stuff:
  - pauseMozzi() - was still declared but not defined -> not usable, anyway
  - unpauseMozzi() - was still declared but not defined -> not usable, anyway
  - Teensy3/4: channel2sc1a -> thought to be unused, removed
  - Teensy2: adc_mapping -> hidden away; use adcPinToChannelNum(), as on all other platforms, instead
+ - removed inclusion of "WProgram.h". If using Arduino versions < 1.0, you need to update, seriously ;-)
+
+Moved headers:
+ - Header files not meant for user inclusion have been moved to "internal"
+ - New sketches should include "Mozzi.h", rather than "MozziGuts.h", thereby documenting, they have been written for Mozzi 2.0+
 
 Documentation bits that still need to find a new home (many other bits were moved around, many, many duplicates merged into a common place, and seom obsoleted bits discarded):
 

examples/01.Basics/Skeleton_Multi/Skeleton_Multi.ino

@@ -4,7 +4,7 @@
  *  Unless you have good reason to do this, it is recommended to base your sketch on the
  *  single-file "Skeleton" example, instead. */
 
-#include <MozziGuts.h>        // at the top of your sketch
+#include <Mozzi.h>        // at the top of your sketch
 
 void setup() {
   startMozzi(64);

examples/01.Basics/Skeleton_Multi/Skeleton_Multi_Unit2.cpp

@@ -1,8 +1,6 @@
-// This file, too, will have to include the Mozzi headers, but in order to avoid "multiple definition" errors,
-// all secondary .cpp files in the sketch must set MOZZI_HEADER_ONLY before including any Mozzi headers.
-// TODO: Maybe that is not even the final word, and this will be required in the end, but it seems a useful intermediate step
-#define MOZZI_HEADER_ONLY
-#include <MozziGuts.h>
+#include <MozziHeadersOnly.h>        // <Mozzi.h> should be included only once in the whole program. Sketches needing
+                                     // core Mozzi functions in more than one .cpp file, shall include MozziHeadersOnly.h
+                                     // in all but one.
 
 AudioOutput_t updateAudio() {
   return MonoOutput::from8Bit(0);  // just a dummy