document some of the structures

src/engine/instrument.h

@@ -388,8 +388,25 @@ struct DivInstrument {
   DivInstrumentC64 c64;
   DivInstrumentAmiga amiga;
   
+  /**
+   * save the instrument to a SafeWriter.
+   * @param w the SafeWriter in question.
+   */
   void putInsData(SafeWriter* w);
+
+  /**
+   * read instrument data in .fui format.
+   * @param reader the reader.
+   * @param version the format version.
+   * @return a DivDataErrors.
+   */
   DivDataErrors readInsData(SafeReader& reader, short version);
+
+  /**
+   * save this instrument to a file.
+   * @param path file path.
+   * @return whether it was successful.
+   */
   bool save(const char* path);
   DivInstrument():
     name(""),

src/engine/macroInt.h

@@ -136,10 +136,29 @@ class DivMacroInt {
         willDam(false), willDvb(false), willEgt(false), willKsl(false),
         willSus(false), willVib(false), willWs(false), willKsr(false) {}
     } op[4];
+
+    /**
+     * trigger macro release.
+     */
     void release();
+
+    /**
+     * trigger next macro tick.
+     */
     void next();
+
+    /**
+     * initialize the macro interpreter.
+     * @param which an instrument, or NULL.
+     */
     void init(DivInstrument* which);
+
+    /**
+     * notify this macro interpreter that an instrument has been deleted.
+     * @param which the instrument in question.
+     */
     void notifyInsDeletion(DivInstrument* which);
+
     DivMacroInt():
       ins(NULL),
       volPos(0),

src/engine/pattern.h

@@ -22,7 +22,19 @@
 struct DivPattern {
   String name;
   short data[256][32];
+
+  /**
+   * copy this pattern to another.
+   * @param dest the destination pattern.
+   */
   void copyOn(DivPattern* dest);
+
+  /**
+   * don't use yet!
+   * @param len the pattern length
+   * @param fxRows number of effect ...columns
+   * @return a SafeReader.
+   */
   SafeReader* compile(int len=256, int fxRows=1);
   DivPattern();
 };
@@ -36,8 +48,20 @@ struct DivChannelData {
   // 2: instrument
   // 3: volume
   // 4-5+: effect/effect value
+  // do NOT access directly unless you know what you're doing!
   DivPattern* data[128];
+
+  /**
+   * get a pattern from this channel, or the empty pattern if not initialized.
+   * @param index the pattern ID.
+   * @param create whether to initialize a new pattern if not init'ed. always use true if you're going to modify it!
+   * @return a DivPattern.
+   */
   DivPattern* getPattern(int index, bool create);
+
+  /**
+   * destroy all patterns on this DivChannelData.
+   */
   void wipePatterns();
   DivChannelData();
 };

src/engine/sample.h

@@ -53,11 +53,44 @@ struct DivSample {
 
   unsigned int samples;
 
+  /**
+   * save this sample to a file.
+   * @param path a path.
+   * @return whether saving succeeded or not.
+   */
   bool save(const char* path);
+
+  /**
+   * @warning DO NOT USE - internal function
+   * initialize sample data.
+   * @param d sample type.
+   * @param count number of samples.
+   * @return whether it was successful.
+   */
   bool initInternal(unsigned char d, int count);
+
+  /**
+   * initialize sample data. make sure you have set `depth` before doing so.
+   * @param count number of samples.
+   * @return whether it was successful.
+   */
   bool init(unsigned int count);
+
+  /**
+   * initialize the rest of sample formats for this sample.
+   */
   void render();
+
+  /**
+   * get the sample data for the current depth.
+   * @return the sample data, or NULL if not created.
+   */
   void* getCurBuf();
+
+  /**
+   * get the sample data length for the current depth.
+   * @return the sample data length.
+   */
   unsigned int getCurBufLen();
   DivSample():
     name(""),

src/engine/song.h

@@ -314,6 +314,10 @@ struct DivSong {
   DivWavetable nullWave;
   DivSample nullSample;
 
+  /**
+   * unloads the song, freeing all memory associated with it.
+   * use before destroying the object.
+   */
   void unload();
 
   DivSong():

src/engine/wavetable.h

@@ -26,8 +26,25 @@ struct DivWavetable {
   int len, min, max;
   int data[256];
 
+  /**
+   * save the wavetable to a SafeWriter.
+   * @param w the SafeWriter in question.
+   */
   void putWaveData(SafeWriter* w);
+
+  /**
+   * read wavetable data in .fuw format.
+   * @param reader the reader.
+   * @param version the format version.
+   * @return a DivDataErrors.
+   */
   DivDataErrors readWaveData(SafeReader& reader, short version);
+
+  /**
+   * save this wavetable to a file.
+   * @param path file path.
+   * @return whether it was successful.
+   */
   bool save(const char* path);
   DivWavetable():
     len(32),