Add more method and field documentation

Mostly for MIDI-specific areas, and general AudioIO fields.

src/AColor.cpp

@@ -558,8 +558,8 @@ const int AColor_midicolors[16][3] = {
    {153, 255, 255},             // 13=lt turquoise
    {153, 153, 255},             // 14=lt blue
    {204, 102, 255},             // 15=lt blue-violet
-   {255, 51, 204}
+   {255, 51, 204}               // 16=lt red-violet
-};                              // 16=lt red-violet
+};
 
 void AColor::MIDIChannel(wxDC * dc, int channel /* 1 - 16 */ )
 {
@@ -571,7 +571,7 @@ void AColor::MIDIChannel(wxDC * dc, int channel /* 1 - 16 */ )
       dc->SetBrush(wxBrush(wxColour(colors[0],
                                     colors[1], colors[2]), wxSOLID));
    } else {
-      dc->SetPen(wxPen(wxColour(153, 153, 153), 1, wxSOLID));// DONT-THEME Midi, unused.
+      dc->SetPen(wxPen(wxColour(153, 153, 153), 1, wxSOLID));
       dc->SetBrush(wxBrush(wxColour(153, 153, 153), wxSOLID));
    }
 

src/AColor.h

@@ -86,6 +86,10 @@ class AColor {
    static void Mute(wxDC * dc, bool on, bool selected, bool soloing);
    static void Solo(wxDC * dc, bool on, bool selected);
 
+   // In all of these, channel is 1-indexed (1 through 16); if out of bounds
+   // (either due to being explicitly set to 0 or due to an allegro file with
+   // more than 16 channels) a gray color is returned.
+
    static void MIDIChannel(wxDC * dc, int channel /* 1 - 16 */ );
    static void LightMIDIChannel(wxDC * dc, int channel /* 1 - 16 */ );
    static void DarkMIDIChannel(wxDC * dc, int channel /* 1 - 16 */ );

src/AudioIO.h

@@ -227,6 +227,8 @@ class AUDACITY_DLL_API AudioIO final {
  public:
    bool SetHasSolo(bool hasSolo);
    bool GetHasSolo() { return mHasSolo; }
+   /// Sets the speed for midi playback, based off of the transcription speed.
+   /// This takes a percentage, so passing 100 will play at normal speed.
    void SetMidiPlaySpeed(double s) { mMidiPlaySpeed = s * 0.01; }
 #endif
 
@@ -494,12 +496,25 @@ private:
    /** \brief How many sample rates to try */
    static const int NumRatesToTry;
 
+   /** \brief True if the end time is before the start time */
    bool ReversedTime() const
    {
       return mT1 < mT0;
    }
+   /** \brief Clamps the given time to be between mT0 and mT1
+    *
+    * Returns the bound if the value is out of bounds; does not wrap.
+    * Returns a time in seconds.
+    * @param absoluteTime A time in seconds, usually mTime
+    */
    double LimitStreamTime(double absoluteTime) const;
 
+   /** \brief Normalizes the given time, clamping it and handling gaps from cut preview.
+    *
+    * Clamps the time (unless scrubbing), and skips over the cut section.
+    * Returns a time in seconds.
+    * @param absoluteTime A time in seconds, usually mTime
+    */
    double NormalizeStreamTime(double absoluteTime) const;
 
    /** \brief Clean up after StartStream if it fails.
@@ -511,35 +526,50 @@ private:
    //   MIDI_PLAYBACK:
    PmStream        *mMidiStream;
    PmError          mLastPmError;
-   long             mMidiLatency; // latency value for PortMidi
+   /// Latency value for PortMidi
-   long             mSynthLatency; // latency of MIDI synthesizer
+   long             mMidiLatency;
-   double           mMidiPlaySpeed; // a copy of TranscriptionToolBar::mPlaySpeed
+   /// Latency of MIDI synthesizer
+   long             mSynthLatency;
+   /// A copy of TranscriptionToolBar::mPlaySpeed - a linear speed offset.
+   /// Should be replaced with use of mTimeTrack
+   double           mMidiPlaySpeed;
 
-   // These fields are used to synchronize MIDI with audio
+   // These fields are used to synchronize MIDI with audio:
-   volatile double  mAudioCallbackOutputTime; // PortAudio's outTime
+
-   volatile long    mNumFrames;         // includes pauses
+   /// PortAudio's outTime
-   volatile long    mNumPauseFrames;    // how many frames of zeros inserted?
+   volatile double  mAudioCallbackOutputTime;
-   volatile long    mPauseTime;         // pause in ms if no audio playback
+   /// Number of frames output, including pauses
-   volatile double  mMidiLoopOffset;    // total of backward jumps
+   volatile long    mNumFrames;
+   /// How many frames of zeros were output due to pauses?
+   volatile long    mNumPauseFrames;
+   /// pause in ms if no audio playback
+   volatile long    mPauseTime;
+   /// total of backward jumps
+   volatile double  mMidiLoopOffset;
    volatile long    mAudioFramesPerBuffer;
-   volatile bool    mMidiPaused;        // used by Midi process to record
+   /// Used by Midi process to record that pause has begun.
-       // that pause has begun. Pause time is accumulated in mPauseTime.
+   /// Pause time is accumulated in mPauseTime.  This variable is shared
-       // This variable is shared so that it can be cleared when playback
+   /// so that it can be cleared when playback begins.
-       // begins.
+   volatile bool    mMidiPaused;
 
    Alg_seq_ptr      mSeq;
    std::unique_ptr<Alg_iterator> mIterator;
-   Alg_event_ptr    mNextEvent; // the next event to play (or null)
+   /// The next event to play (or null)
-   double           mNextEventTime; // the time of the next event
+   Alg_event_ptr    mNextEvent;
-                       // (note that this could be a note's time+duration)
+   /// Time at which the next event should be output, measured in seconds.
-   NoteTrack        *mNextEventTrack; // track of next event
+   /// Note that this could be a note's time+duration for note offs.
-   bool             mMidiOutputComplete; // true when output reaches mT1
+   double           mNextEventTime;
-   bool             mNextIsNoteOn; // is the next event a note-off?
+   /// Track of next event
+   NoteTrack        *mNextEventTrack;
+   /// True when output reaches mT1
+   bool             mMidiOutputComplete;
+   /// Is the next event a note-on?
+   bool             mNextIsNoteOn;
    //   int                 mCnt;
-   // mMidiStreamActive tells when mMidiStream is open for output
+   /// mMidiStreamActive tells when mMidiStream is open for output
    bool             mMidiStreamActive;
-   // when true, mSendMidiState means send only updates, not note-on's,
+   /// when true, mSendMidiState means send only updates, not note-on's,
-   // used to send state changes that precede the selected notes
+   /// used to send state changes that precede the selected notes
    bool             mSendMidiState;
    NoteTrackArray   mMidiPlaybackTracks;
 #endif
@@ -575,20 +605,30 @@ private:
    volatile int        mStreamToken;
    static int          mNextStreamToken;
    double              mFactor;
+   /// Audio playback rate in samples per second
    double              mRate;
-   double              mT0; // playback starts at offset of mT0
+   /// Playback starts at offset of mT0, which is measured in seconds.
-   double              mT1; // and ends at offset of mT1
+   double              mT0;
-   double              mTime; // current time position during playback
+   /// Playback ends at offset of mT1, which is measured in seconds.  Note that mT1 may be less than mT0 during scrubbing.
-   double              mWarpedTime; // current time after warping, starting at zero (unlike mTime)
+   double              mT1;
-   double              mWarpedLength; // total length after warping
+   /// Current time position during playback, in seconds.  Between mT0 and mT1.
+   double              mTime;
+   /// Current time after warping, starting at zero (unlike mTime).
+   /// Length in real seconds between mT0 and mTime.
+   double              mWarpedTime;
+   /// Total length after warping via a time track.
+   /// Length in real seconds between mT0 and mT1.  Always positive.
+   double              mWarpedLength;
    double              mSeek;
    double              mPlaybackRingBufferSecs;
    double              mCaptureRingBufferSecs;
    size_t              mPlaybackSamplesToCopy;
    double              mMinCaptureSecsToCopy;
+   /// True if audio playback is paused
    bool                mPaused;
    PaStream           *mPortStreamV19;
    bool                mSoftwarePlaythrough;
+   /// True if Sound Activated Recording is enabled
    bool                mPauseRec;
    float               mSilenceLevel;
    unsigned int        mNumCaptureChannels;