Version 1.1.20vdr-1.1.20

- Now checking if there is a connection to the keyboard (thanks to Jaakko Hyvätti)
  and only creating the KBD remote control if VDR is running in the foreground.
- Fixed taking an active SVDRP connection into account when doing shutdown (thanks
  to Gregoire Favre for reporting this one).
- Changed setting of CXX and CXXFLAGS variables in Makefile, so that an externally
  defined value will be taken if present (suggested by Robert Schiele).
  Plugin authors should please change the lines

  CXX      = g++
  CXXFLAGS = -O2 -Wall -Woverloaded-virtual

  in their Makefile to

  CXX      ?= g++
  CXXFLAGS ?= -O2 -Wall -Woverloaded-virtual

- Fixed recording overlapping timers on the same channel in case
  DO_REC_AND_PLAY_ON_PRIMARY_DEVICE and/or DO_MULTIPLE_RECORDINGS is not defined
  (thanks to Jaakko Hyvätti).
- No longer stopping/restarting the DMX when switching audio channels (thanks to
  Sven Goethel).
- Fixed high CPU load in 'Transfer Mode' (thanks to Oliver Endriss).
- If a PC keyboard is used as remote control, the string entry fields in the
  menus now accept character input directly (however, this works only for keys that
  are not otherwise defined as remote control keys). Also, plugins can switch the
  cKbdRemote class into "raw mode", where all keyboard input will be made available
  through the new 'kKbd' key code and none of it will be processed as normal remote
  control functions (thanks to Jan Rieger for suggestions and testing).
- Fixed deleting characters in string entry fields in 'insert' mode.
- Now using "Doxygen" to generate source documentation (thanks to Walter Stroebel
  for providing an initial 'Doxyfile' configuration and adjusting some comments).
  See INSTALL for information how to do this. Some function descriptions have
  already been adapted to Doxygen, more will follow.

1 files changed, 191 insertions, 175 deletions

diff --git a/device.h b/device.h
index cc2be79..f18699c 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: