Using 'Doxygen' to generate source code documentation

1 files changed, 191 insertions, 175 deletions

diff --git a/device.h b/device.h
index cc2be790..f18699c4 100644
--- a/device.h
+++ b/device.h
@@ -4,7 +4,7 @@
  * See the main source file 'vdr.c' for copyright information and
  * how to reach the author.
  *
- * $Id: device.h 1.27 2002/11/03 11:16:11 kls Exp $
+ * $Id: device.h 1.28 2002/12/15 14:40:11 kls Exp $
  */
 
 #ifndef __DEVICE_H
@@ -50,6 +50,8 @@ class cPlayer;
 class cReceiver;
 class cSpuDecoder;
 
+/// The cDevice class is the base from which actual devices can be derived.
+
 class cDevice : public cThread {
 private:
   static int numDevices;
@@ -58,32 +60,35 @@ private:
   static cDevice *primaryDevice;
 public:
   static int NumDevices(void) { return numDevices; }
-         // Returns the total number of devices.
+         ///< Returns the total number of devices.
   static void SetUseDevice(int n);
-         // Sets the 'useDevice' flag of the given device.
-         // If this function is not called before initializing, all devices
-         // will be used.
+         ///< Sets the 'useDevice' flag of the given device.
+         ///< If this function is not called before initializing, all devices
+         ///< will be used.
   static bool UseDevice(int n) { return useDevice == 0 || (useDevice & (1 << n)) != 0; }
-         // Tells whether the device with the given card index shall be used in
-         // this instance of VDR.
+         ///< Tells whether the device with the given card index shall be used in
+         ///< this instance of VDR.
   static bool SetPrimaryDevice(int n);
-         // Sets the primary device to 'n' (which must be in the range
-         // 1...numDevices) and returns true if this was possible.
+         ///< Sets the primary device to 'n'.
+         ///< \param n must be in the range 1...numDevices.
+         ///< \return true if this was possible.
   static cDevice *PrimaryDevice(void) { return primaryDevice; }
-         // Returns the primary device.
+         ///< Returns the primary device.
   static cDevice *GetDevice(int Index);
-         // Returns the device with the Index (if Index is in the range
-         // 0..numDevices-1, NULL otherwise).
+         ///< Gets the device with the given Index.
+         ///< \param Index must be in the range 0..numDevices-1.
+         ///< \return A pointer to the device, or NULL if the Index was invalid.
   static cDevice *GetDevice(const cChannel *Channel, int Priority = -1, bool *NeedsDetachReceivers = NULL);
-         // Returns a device that is able to receive the given Channel at the
-         // given Priority (see ProvidesChannel() for more information on how
-         // priorities are handled, and the meaning of NeedsDetachReceivers).
+         ///< Returns a device that is able to receive the given Channel at the
+         ///< given Priority.
+         ///< See ProvidesChannel() for more information on how
+         ///< priorities are handled, and the meaning of NeedsDetachReceivers.
   static void SetCaCaps(int Index = -1);
-         // Sets the CaCaps of the given device according to the Setup data.
-         // By default the CaCaps of all devices are set.
+         ///< Sets the CaCaps of the given device according to the Setup data.
+         ///< By default the CaCaps of all devices are set.
   static void Shutdown(void);
-         // Closes down all devices.
-         // Must be called at the end of the program.
+         ///< Closes down all devices.
+         ///< Must be called at the end of the program.
 private:
   static int nextCardIndex;
   int cardIndex;
@@ -92,49 +97,50 @@ protected:
   cDevice(void);
   virtual ~cDevice();
   static int NextCardIndex(int n = 0);
-         // Each device in a given machine must have a unique card index, which
-         // will be used to identify the device for assigning Ca parameters and
-         // deciding whether to actually use that device in this particular
-         // instance of VDR. Every time a new cDevice is created, it will be
-         // given the current nextCardIndex, and then nextCardIndex will be
-         // automatically incremented by 1. A derived class can determine whether
-         // a given device shall be used by checking UseDevice(NextCardIndex()).
-         // If a device is skipped, or if there are possible device indexes left
-         // after a derived class has set up all its devices, NextCardIndex(n)
-         // must be called, where n is the number of card indexes to skip.
+         ///< Calculates the next card index.
+         ///< Each device in a given machine must have a unique card index, which
+         ///< will be used to identify the device for assigning Ca parameters and
+         ///< deciding whether to actually use that device in this particular
+         ///< instance of VDR. Every time a new cDevice is created, it will be
+         ///< given the current nextCardIndex, and then nextCardIndex will be
+         ///< automatically incremented by 1. A derived class can determine whether
+         ///< a given device shall be used by checking UseDevice(NextCardIndex()).
+         ///< If a device is skipped, or if there are possible device indexes left
+         ///< after a derived class has set up all its devices, NextCardIndex(n)
+         ///< must be called, where n is the number of card indexes to skip.
   virtual void MakePrimaryDevice(bool On);
-         // Informs a device that it will be the primary device. If there is
-         // anything the device needs to set up when it becomes the primary
-         // device (On = true) or to shut down when it no longer is the primary
-         // device (On = false), it should do so in this function.
+         ///< Informs a device that it will be the primary device. If there is
+         ///< anything the device needs to set up when it becomes the primary
+         ///< device (On = true) or to shut down when it no longer is the primary
+         ///< device (On = false), it should do so in this function.
 public:
   bool IsPrimaryDevice(void) const { return this == primaryDevice; }
   int CardIndex(void) const { return cardIndex; }
-         // Returns the card index of this device (0 ... MAXDEVICES - 1).
+         ///< Returns the card index of this device (0 ... MAXDEVICES - 1).
   int DeviceNumber(void) const;
-         // Returns number of this device (0 ... MAXDEVICES - 1).
+         ///< Returns the number of this device (0 ... MAXDEVICES - 1).
   int ProvidesCa(int Ca) const;
-         // Checks whether this device provides the given value in its
-         // caCaps. Returns 0 if the value is not provided, 1 if only this
-         // value is provided, and > 1 if this and other values are provided.
-         // If the given value is equal to the number of this device,
-         // 1 is returned. If it is 0 (FTA), 1 plus the number of other values
-         // in caCaps is returned.
+         ///< Checks whether this device provides the given value in its
+         ///< caCaps. Returns 0 if the value is not provided, 1 if only this
+         ///< value is provided, and > 1 if this and other values are provided.
+         ///< If the given value is equal to the number of this device,
+         ///< 1 is returned. If it is 0 (FTA), 1 plus the number of other values
+         ///< in caCaps is returned.
   virtual bool HasDecoder(void) const;
-         // Tells whether this device has an MPEG decoder.
+         ///< Tells whether this device has an MPEG decoder.
 
 // OSD facilities
 
 public:
   virtual cOsdBase *NewOsd(int x, int y);
-         // Creates a new cOsdBase object that can be used by the cOsd class
-         // to display information on the screen, with the upper left corner
-         // of the OSD at the given coordinates. If a derived cDevice doesn't
-         // implement this function, NULL will be returned by default (which
-         // means the device has no OSD capabilities).
+         ///< Creates a new cOsdBase object that can be used by the cOsd class
+         ///< to display information on the screen, with the upper left corner
+         ///< of the OSD at the given coordinates. If a derived cDevice doesn't
+         ///< implement this function, NULL will be returned by default (which
+         ///< means the device has no OSD capabilities).
   virtual cSpuDecoder *GetSpuDecoder(void);
-         // Returns a pointer to the device's SPU decoder (or NULL, if this
-         // device doesn't have an SPU decoder).
+         ///< Returns a pointer to the device's SPU decoder (or NULL, if this
+         ///< device doesn't have an SPU decoder).
 
 // Channel facilities
 
@@ -142,38 +148,38 @@ protected:
   static int currentChannel;
 public:
   virtual bool ProvidesSource(int Source) const;
-         // Returns true if this device can provide the given source.
+         ///< Returns true if this device can provide the given source.
   virtual bool ProvidesChannel(const cChannel *Channel, int Priority = -1, bool *NeedsDetachReceivers = NULL) const;
-         // Returns true if this device can provide the given channel.
-         // In case the device has cReceivers attached to it or it is the primary
-         // device, Priority is used to decide whether the caller's request can
-         // be honored.
-         // The special Priority value -1 will tell the caller whether this device
-         // is principally able to provide the given Channel, regardless of any
-         // attached cReceivers.
-         // If NeedsDetachReceivers is given, the resulting value in it will tell the
-         // caller whether or not it will have to detach any currently attached
-         // receivers from this device before calling SwitchChannel. Note
-         // that the return value in NeedsDetachReceivers is only meaningful if the
-         // function itself actually returns true.
-         // The default implementation always returns false, so a derived cDevice
-         // class that can provide channels must implement this function.
+         ///< Returns true if this device can provide the given channel.
+         ///< In case the device has cReceivers attached to it or it is the primary
+         ///< device, Priority is used to decide whether the caller's request can
+         ///< be honored.
+         ///< The special Priority value -1 will tell the caller whether this device
+         ///< is principally able to provide the given Channel, regardless of any
+         ///< attached cReceivers.
+         ///< If NeedsDetachReceivers is given, the resulting value in it will tell the
+         ///< caller whether or not it will have to detach any currently attached
+         ///< receivers from this device before calling SwitchChannel. Note
+         ///< that the return value in NeedsDetachReceivers is only meaningful if the
+         ///< function itself actually returns true.
+         ///< The default implementation always returns false, so a derived cDevice
+         ///< class that can provide channels must implement this function.
   bool SwitchChannel(const cChannel *Channel, bool LiveView);
-         // Switches the device to the given Channel, initiating transfer mode
-         // if necessary.
+         ///< Switches the device to the given Channel, initiating transfer mode
+         ///< if necessary.
   static bool SwitchChannel(int Direction);
-         // Switches the primary device to the next available channel in the given
-         // Direction (only the sign of Direction is evaluated, positive values
-         // switch to higher channel numbers).
+         ///< Switches the primary device to the next available channel in the given
+         ///< Direction (only the sign of Direction is evaluated, positive values
+         ///< switch to higher channel numbers).
 private:
   eSetChannelResult SetChannel(const cChannel *Channel, bool LiveView);
-         // Sets the device to the given channel (general setup).
+         ///< Sets the device to the given channel (general setup).
 protected:
   virtual bool SetChannelDevice(const cChannel *Channel, bool LiveView);
-         // Sets the device to the given channel (actual physical setup).
+         ///< Sets the device to the given channel (actual physical setup).
 public:
   static int CurrentChannel(void) { return primaryDevice ? currentChannel : 0; }
-         // Returns the number of the current channel on the primary device.
+         ///< Returns the number of the current channel on the primary device.
 
 // PID handle facilities
 
@@ -191,33 +197,43 @@ protected:
     };
   cPidHandle pidHandles[MAXPIDHANDLES];
   bool HasPid(int Pid) const;
-         // Returns true if this device is currently receiving the given PID.
+         ///< Returns true if this device is currently receiving the given PID.
   bool AddPid(int Pid, ePidType PidType = ptOther);
-         // Adds a PID to the set of PIDs this device shall receive.
+         ///< Adds a PID to the set of PIDs this device shall receive.
   void DelPid(int Pid);
-         // Deletes a PID from the set of PIDs this device shall receive.
+         ///< Deletes a PID from the set of PIDs this device shall receive.
   virtual bool SetPid(cPidHandle *Handle, int Type, bool On);
-         // Does the actual PID setting on this device.
-         // On indicates whether the PID shall be added or deleted.
-         // Handle->handle can be used by the device to store information it
-         // needs to receive this PID (for instance a file handle).
-         // Handle->used indicated how many receivers are using this PID.
-         // Type indicates some special types of PIDs, which the device may
-         // need to set in a specific way.
+         ///< Does the actual PID setting on this device.
+         ///< On indicates whether the PID shall be added or deleted.
+         ///< Handle->handle can be used by the device to store information it
+         ///< needs to receive this PID (for instance a file handle).
+         ///< Handle->used indicated how many receivers are using this PID.
+         ///< Type indicates some special types of PIDs, which the device may
+         ///< need to set in a specific way.
 
 // Image Grab facilities
 
 public:
   virtual bool GrabImage(const char *FileName, bool Jpeg = true, int Quality = -1, int SizeX = -1, int SizeY = -1);
-         // Grabs the currently visible screen image into the given file, with the
-         // given parameters.
+         ///< Capture a single frame as an image.
+         ///< Grabs the currently visible screen image into the given file, with the
+         ///< given parameters.
+         ///< \param FileName The name of the file to write. Should include the proper extension.
+         ///< \param Jpeg If true will write a JPEG file. Otherwise a PNM file will be written.
+         ///< \param Quality The compression factor for JPEG. 1 will create a very blocky
+         ///<        and small image, 70..80 will yield reasonable quality images while keeping the
+         ///<        image file size around 50 KB for a full frame. The default will create a big
+         ///<        but very high quality image.
+         ///< \param SizeX The number of horizontal pixels in the frame (default is the current screen width).
+         ///< \param SizeY The number of vertical pixels in the frame (default is the current screen height).
+         ///< \return True if all went well. */
 
 // Video format facilities
 
 public:
   virtual void SetVideoFormat(bool VideoFormat16_9);
-         // Sets the output video format to either 16:9 or 4:3 (only useful
-         // if this device has an MPEG decoder).
+         ///< Sets the output video format to either 16:9 or 4:3 (only useful
+         ///< if this device has an MPEG decoder).
 
 // Audio facilities
 
@@ -226,51 +242,51 @@ private:
   int volume;
 protected:
   virtual void SetVolumeDevice(int Volume);
-       // Sets the audio volume on this device (Volume = 0...255).
+       ///< Sets the audio volume on this device (Volume = 0...255).
   virtual int NumAudioTracksDevice(void) const;
-       // Returns the number of audio tracks that are currently available on this
-       // device. The default return value is 0, meaning that this device
-       // doesn't have multiple audio track capabilities. The return value may
-       // change with every call and need not necessarily be the number of list
-       // entries returned by GetAudioTracksDevice(). This function is mainly called to
-       // decide whether there should be an "Audio" button in a menu.
+       ///< Returns the number of audio tracks that are currently available on this
+       ///< device. The default return value is 0, meaning that this device
+       ///< doesn't have multiple audio track capabilities. The return value may
+       ///< change with every call and need not necessarily be the number of list
+       ///< entries returned by GetAudioTracksDevice(). This function is mainly called to
+       ///< decide whether there should be an "Audio" button in a menu.
   virtual const char **GetAudioTracksDevice(int *CurrentTrack = NULL) const;
-       // Returns a list of currently available audio tracks. The last entry in the
-       // list must be NULL. The number of entries does not necessarily have to be
-       // the same as returned by a previous call to NumAudioTracksDevice().
-       // If CurrentTrack is given, it will be set to the index of the current track
-       // in the returned list. Note that the list must not be changed after it has
-       // been returned by a call to GetAudioTracksDevice()! The only time the list may
-       // change is *inside* the GetAudioTracksDevice() function.
-       // By default the return value is NULL and CurrentTrack, if given, will not
-       // have any meaning.
+       ///< Returns a list of currently available audio tracks. The last entry in the
+       ///< list must be NULL. The number of entries does not necessarily have to be
+       ///< the same as returned by a previous call to NumAudioTracksDevice().
+       ///< If CurrentTrack is given, it will be set to the index of the current track
+       ///< in the returned list. Note that the list must not be changed after it has
+       ///< been returned by a call to GetAudioTracksDevice()! The only time the list may
+       ///< change is *inside* the GetAudioTracksDevice() function.
+       ///< By default the return value is NULL and CurrentTrack, if given, will not
+       ///< have any meaning.
   virtual void SetAudioTrackDevice(int Index);
-       // Sets the current audio track to the given value, which should be within the
-       // range of the list returned by a previous call to GetAudioTracksDevice()
-       // (otherwise nothing will happen).
+       ///< Sets the current audio track to the given value, which should be within the
+       ///< range of the list returned by a previous call to GetAudioTracksDevice()
+       ///< (otherwise nothing will happen).
 public:
   bool IsMute(void) const { return mute; }
   bool ToggleMute(void);
-       // Turns the volume off or on and returns the new mute state.
+       ///< Turns the volume off or on and returns the new mute state.
   void SetVolume(int Volume, bool Absolute = false);
-       // Sets the volume to the given value, either absolutely or relative to
-       // the current volume.
+       ///< Sets the volume to the given value, either absolutely or relative to
+       ///< the current volume.
   static int CurrentVolume(void) { return primaryDevice ? primaryDevice->volume : 0; }//XXX???
   int NumAudioTracks(void) const;
-       // Returns the number of audio tracks that are currently available on this
-       // device or a player attached to it.
+       ///< Returns the number of audio tracks that are currently available on this
+       ///< device or a player attached to it.
   const char **GetAudioTracks(int *CurrentTrack = NULL) const;
-       // Returns a list of currently available audio tracks. The last entry in the
-       // list is NULL. The number of entries does not necessarily have to be
-       // the same as returned by a previous call to NumAudioTracks().
-       // If CurrentTrack is given, it will be set to the index of the current track
-       // in the returned list.
-       // By default the return value is NULL and CurrentTrack, if given, will not
-       // have any meaning.
+       ///< Returns a list of currently available audio tracks. The last entry in the
+       ///< list is NULL. The number of entries does not necessarily have to be
+       ///< the same as returned by a previous call to NumAudioTracks().
+       ///< If CurrentTrack is given, it will be set to the index of the current track
+       ///< in the returned list.
+       ///< By default the return value is NULL and CurrentTrack, if given, will not
+       ///< have any meaning.
   void SetAudioTrack(int Index);
-       // Sets the current audio track to the given value, which should be within the
-       // range of the list returned by a previous call to GetAudioTracks() (otherwise
-       // nothing will happen).
+       ///< Sets the current audio track to the given value, which should be within the
+       ///< range of the list returned by a previous call to GetAudioTracks() (otherwise
+       ///< nothing will happen).
 
 // Player facilities
 
@@ -279,54 +295,54 @@ private:
   bool playerDetached;
 protected:
   virtual bool CanReplay(void) const;
-       // Returns true if this device can currently start a replay session.
+       ///< Returns true if this device can currently start a replay session.
   virtual bool SetPlayMode(ePlayMode PlayMode);
-       // Sets the device into the given play mode.
-       // Returns true if the operation was successful.
+       ///< Sets the device into the given play mode.
+       ///< \return true if the operation was successful.
 public:
   virtual void TrickSpeed(int Speed);
-       // Sets the device into a mode where replay is done slower.
-       // Every single frame shall then be displayed the given number of
-       // times.
+       ///< Sets the device into a mode where replay is done slower.
+       ///< Every single frame shall then be displayed the given number of
+       ///< times.
   virtual void Clear(void);
-       // Clears all video and audio data from the device.
-       // A derived class must call the base class function to make sure
-       // all registered cAudio objects are notified.
+       ///< Clears all video and audio data from the device.
+       ///< A derived class must call the base class function to make sure
+       ///< all registered cAudio objects are notified.
   virtual void Play(void);
-       // Sets the device into play mode (after a previous trick
-       // mode).
+       ///< Sets the device into play mode (after a previous trick
+       ///< mode).
   virtual void Freeze(void);
-       // Puts the device into "freeze frame" mode.
+       ///< Puts the device into "freeze frame" mode.
   virtual void Mute(void);
-       // Turns off audio while replaying.
-       // A derived class must call the base class function to make sure
-       // all registered cAudio objects are notified.
+       ///< Turns off audio while replaying.
+       ///< A derived class must call the base class function to make sure
+       ///< all registered cAudio objects are notified.
   virtual void StillPicture(const uchar *Data, int Length);
-       // Displays the given I-frame as a still picture.
+       ///< Displays the given I-frame as a still picture.
   virtual bool Poll(cPoller &Poller, int TimeoutMs = 0);
-       // Returns true if the device itself or any of the file handles in
-       // Poller is ready for further action.
-       // If TimeoutMs is not zero, the device will wait up to the given number
-       // of milleseconds before returning in case there is no immediate
-       // need for data.
+       ///< Returns true if the device itself or any of the file handles in
+       ///< Poller is ready for further action.
+       ///< If TimeoutMs is not zero, the device will wait up to the given number
+       ///< of milleseconds before returning in case there is no immediate
+       ///< need for data.
   virtual int PlayVideo(const uchar *Data, int Length);
-       // Actually plays the given data block as video. The data must be
-       // part of a PES (Packetized Elementary Stream) which can contain
-       // one video and one audio strem.
+       ///< Actually plays the given data block as video. The data must be
+       ///< part of a PES (Packetized Elementary Stream) which can contain
+       ///< one video and one audio strem.
   virtual void PlayAudio(const uchar *Data, int Length);
-       // Plays additional audio streams, like Dolby Digital.
-       // A derived class must call the base class function to make sure data
-       // is distributed to all registered cAudio objects.
+       ///< Plays additional audio streams, like Dolby Digital.
+       ///< A derived class must call the base class function to make sure data
+       ///< is distributed to all registered cAudio objects.
   bool Replaying(void) const;
-       // Returns true if we are currently replaying.
+       ///< Returns true if we are currently replaying.
   void StopReplay(void);
-       // Stops the current replay session (if any).
+       ///< Stops the current replay session (if any).
   bool AttachPlayer(cPlayer *Player);
-       // Attaches the given player to this device.
+       ///< Attaches the given player to this device.
   void Detach(cPlayer *Player);
-       // Detaches the given player from this device.
+       ///< Detaches the given player from this device.
   bool PlayerDetached(void);
-       // Returns true if a player has been detached and resets the 'playerDetached' flag.
+       ///< Returns true if a player has been detached and resets the 'playerDetached' flag.
 
 // Receiver facilities
 
@@ -335,39 +351,39 @@ private:
   int CanShift(int Ca, int Priority, int UsedCards = 0) const;
 protected:
   int Priority(void) const;
-      // Returns the priority of the current receiving session (0..MAXPRIORITY),
-      // or -1 if no receiver is currently active. The primary device will
-      // always return at least Setup.PrimaryLimit-1.
+      ///< Returns the priority of the current receiving session (0..MAXPRIORITY),
+      ///< or -1 if no receiver is currently active. The primary device will
+      ///< always return at least Setup.PrimaryLimit-1.
   virtual bool OpenDvr(void);
-      // Opens the DVR of this device and prepares it to deliver a Transport
-      // Stream for use in a cReceiver.
+      ///< Opens the DVR of this device and prepares it to deliver a Transport
+      ///< Stream for use in a cReceiver.
   virtual void CloseDvr(void);
-      // Shuts down the DVR.
+      ///< Shuts down the DVR.
   virtual bool GetTSPacket(uchar *&Data);
-      // Gets exactly one TS packet from the DVR of this device and returns
-      // a pointer to it in Data. Only the first 188 bytes (TS_SIZE) Data
-      // points to are valid and may be accessed. If there is currently no
-      // new data available, Data will be set to NULL. The function returns
-      // false in case of a non recoverable error, otherwise it returns true,
-      // even if Data is NULL.
+      ///< Gets exactly one TS packet from the DVR of this device and returns
+      ///< a pointer to it in Data. Only the first 188 bytes (TS_SIZE) Data
+      ///< points to are valid and may be accessed. If there is currently no
+      ///< new data available, Data will be set to NULL. The function returns
+      ///< false in case of a non recoverable error, otherwise it returns true,
+      ///< even if Data is NULL.
 public:
   int  Ca(void) const;
-       // Returns the ca of the current receiving session(s).
+       ///< Returns the ca of the current receiving session(s).
   bool Receiving(bool CheckAny = false) const;
-       // Returns true if we are currently receiving.
+       ///< Returns true if we are currently receiving.
   bool AttachReceiver(cReceiver *Receiver);
-       // Attaches the given receiver to this device.
+       ///< Attaches the given receiver to this device.
   void Detach(cReceiver *Receiver);
-       // Detaches the given receiver from this device.
+       ///< Detaches the given receiver from this device.
   };
 
-// Derived cDevice classes that can receive channels will have to provide
-// Transport Stream (TS) packets one at a time. cTSBuffer implements a
-// simple buffer that allows the device to read a larger amount of data
-// from the driver with each call to Read(), thus avoiding the overhead
-// of getting each TS packet separately from the driver. It also makes
-// sure the returned data points to a TS packet and automatically
-// re-synchronizes after broken packet.
+/// Derived cDevice classes that can receive channels will have to provide
+/// Transport Stream (TS) packets one at a time. cTSBuffer implements a
+/// simple buffer that allows the device to read a larger amount of data
+/// from the driver with each call to Read(), thus avoiding the overhead
+/// of getting each TS packet separately from the driver. It also makes
+/// sure the returned data points to a TS packet and automatically
+/// re-synchronizes after broken packet.
 
 class cTSBuffer {
 private: