diff --git a/HISTORY b/HISTORY index d114f1eb..ce9791b7 100644 --- a/HISTORY +++ b/HISTORY @@ -7631,3 +7631,6 @@ Video Disk Recorder Revision History - Added missing 'const' to cDevice::HasProgramme() and cDevice::HasLock(). - Fixed determining the priority of the primary device in case it is neither replaying nor receiving a live channel. +- Removed all \return and \param tags from comment lines marked with "///<" for Doxygen. + There was only a rather small number of these, and I would probably always forget to + put them in place when writing future comments, so I decided to drop them entirely. diff --git a/ci.c b/ci.c index 904697eb..834647bb 100644 --- a/ci.c +++ b/ci.c @@ -4,7 +4,7 @@ * See the main source file 'vdr.c' for copyright information and * how to reach the author. * - * $Id: ci.c 2.10 2012/10/07 11:11:18 kls Exp $ + * $Id: ci.c 2.11 2013/02/16 15:16:14 kls Exp $ */ #include "ci.h" @@ -35,7 +35,7 @@ static bool DumpDateTime = false; static const uint8_t *GetLength(const uint8_t *Data, int &Length) ///< Gets the length field from the beginning of Data. -///< \return Returns a pointer to the first byte after the length and +///< Returns a pointer to the first byte after the length and ///< stores the length value in Length. { Length = *Data++; @@ -50,7 +50,7 @@ static const uint8_t *GetLength(const uint8_t *Data, int &Length) static uint8_t *SetLength(uint8_t *Data, int Length) ///< Sets the length field at the beginning of Data. -///< \return Returns a pointer to the first byte after the length. +///< Returns a pointer to the first byte after the length. { uint8_t *p = Data; if (Length < 128) @@ -70,7 +70,7 @@ static uint8_t *SetLength(uint8_t *Data, int Length) static char *CopyString(int Length, const uint8_t *Data) ///< Copies the string at Data. -///< \return Returns a pointer to a newly allocated string. +///< Returns a pointer to a newly allocated string. { // Some CAMs send funny characters at the beginning of strings. // Let's just skip them: @@ -88,7 +88,7 @@ static char *CopyString(int Length, const uint8_t *Data) static char *GetString(int &Length, const uint8_t **Data) ///< Gets the string at Data. -///< \return Returns a pointer to a newly allocated string, or NULL in case of error. +///< Returns a pointer to a newly allocated string, or NULL in case of error. ///< Upon return Length and Data represent the remaining data after the string has been skipped. { if (Length > 0 && Data && *Data) { @@ -371,7 +371,7 @@ cCiSession::~cCiSession() int cCiSession::GetTag(int &Length, const uint8_t **Data) ///< Gets the tag at Data. -///< \return Returns the actual tag, or AOT_NONE in case of error. +///< Returns the actual tag, or AOT_NONE in case of error. ///< Upon return Length and Data represent the remaining data after the tag has been skipped. { if (Length >= 3 && Data && *Data) { @@ -959,7 +959,7 @@ cCiMMI::~cCiMMI() char *cCiMMI::GetText(int &Length, const uint8_t **Data) ///< Gets the text at Data. -///< \return Returns a pointer to a newly allocated string, or NULL in case of error. +///< Returns a pointer to a newly allocated string, or NULL in case of error. ///< Upon return Length and Data represent the remaining data after the text has been skipped. { int Tag = GetTag(Length, Data); diff --git a/device.h b/device.h index 9104cfc6..fd010d41 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 2.46 2013/02/16 12:47:18 kls Exp $ + * $Id: device.h 2.47 2013/02/16 15:20:01 kls Exp $ */ #ifndef __DEVICE_H @@ -116,7 +116,7 @@ public: ///< Waits until all devices have become ready, or the given Timeout ///< (seconds) has expired. While waiting, the Ready() function of each ///< device is called in turn, until they all return true. - ///< \return True if all devices have become ready within the given + ///< Returns true if all devices have become ready within the given ///< timeout. static void SetUseDevice(int n); ///< Sets the 'useDevice' flag of the given device. @@ -127,8 +127,8 @@ public: ///< this instance of VDR. static bool SetPrimaryDevice(int n); ///< Sets the primary device to 'n'. - ///< \param n must be in the range 1...numDevices. - ///< \return true if this was possible. + ///< n must be in the range 1...numDevices. + ///< Returns true if this was possible. static cDevice *PrimaryDevice(void) { return primaryDevice; } ///< Returns the primary device. static cDevice *ActualDevice(void); @@ -136,8 +136,8 @@ public: ///< primary device otherwise. static cDevice *GetDevice(int Index); ///< 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. + ///< Index must be in the range 0..numDevices-1. + ///< Returns a pointer to the device, or NULL if the Index was invalid. static cDevice *GetDevice(const cChannel *Channel, int Priority, bool LiveView, bool Query = false); ///< Returns a device that is able to receive the given Channel at the ///< given Priority, with the least impact on active recordings and @@ -432,19 +432,19 @@ public: public: virtual uchar *GrabImage(int &Size, bool Jpeg = true, int Quality = -1, int SizeX = -1, int SizeY = -1); ///< Grabs the currently visible screen image. - ///< \param Size The size of the returned data block. - ///< \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 A pointer to the grabbed image data, or NULL in case of an error. + ///< Size is the size of the returned data block. + ///< If Jpeg is true it will write a JPEG file. Otherwise a PNM file will be written. + ///< Quality is 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. + ///< SizeX is the number of horizontal pixels in the frame (default is the current screen width). + ///< SizeY is the number of vertical pixels in the frame (default is the current screen height). + ///< Returns a pointer to the grabbed image data, or NULL in case of an error. ///< The caller takes ownership of the returned memory and must free() it once it isn't needed any more. bool GrabImageFile(const char *FileName, bool Jpeg = true, int Quality = -1, int SizeX = -1, int SizeY = -1); ///< Calls GrabImage() and stores the resulting image in a file with the given name. - ///< \return True if all went well. + ///< Returns true if all went well. ///< The caller is responsible for making sure that the given file name ///< doesn't lead to overwriting any important other file. @@ -509,7 +509,7 @@ public: ///< Index tells which track of the given basic type is meant. ///< If Id is 0 any existing id will be left untouched and only the ///< given Language and Description will be set. - ///< \return Returns true if the track was set correctly, false otherwise. + ///< Returns true if the track was set correctly, false otherwise. const tTrackId *GetTrack(eTrackType Type); ///< Returns a pointer to the given track id, or NULL if Type is not ///< less than ttMaxTrackTypes. @@ -525,14 +525,14 @@ public: eTrackType GetCurrentAudioTrack(void) const { return currentAudioTrack; } bool SetCurrentAudioTrack(eTrackType Type); ///< Sets the current audio track to the given Type. - ///< \return Returns true if Type is a valid audio track, false otherwise. + ///< Returns true if Type is a valid audio track, false otherwise. eTrackType GetCurrentSubtitleTrack(void) const { return currentSubtitleTrack; } bool SetCurrentSubtitleTrack(eTrackType Type, bool Manual = false); ///< Sets the current subtitle track to the given Type. ///< IF Manual is true, no automatic preferred subtitle language selection ///< will be done for the rest of the current replay session, or until ///< the channel is changed. - ///< \return Returns true if Type is a valid subtitle track, false otherwise. + ///< Returns true if Type is a valid subtitle track, false otherwise. void EnsureAudioTrack(bool Force = false); ///< Makes sure an audio track is selected that is actually available. ///< If Force is true, the language and Dolby Digital settings will @@ -593,13 +593,13 @@ protected: ///< Returns true if this device can currently start a replay session. virtual bool SetPlayMode(ePlayMode PlayMode); ///< Sets the device into the given play mode. - ///< \return true if the operation was successful. + ///< Returns true if the operation was successful. virtual int PlayVideo(const uchar *Data, int Length); ///< Plays the given data block as video. ///< Data points to exactly one complete PES packet of the given Length. ///< PlayVideo() shall process the packet either as a whole (returning ///< Length) or not at all (returning 0 or -1 and setting 'errno' accordingly). - ///< \return Returns the number of bytes actually taken from Data, or -1 + ///< Returns the number of bytes actually taken from Data, or -1 ///< in case of an error. virtual int PlayAudio(const uchar *Data, int Length, uchar Id); ///< Plays the given data block as audio. @@ -607,14 +607,14 @@ protected: ///< Id indicates the type of audio data this packet holds. ///< PlayAudio() shall process the packet either as a whole (returning ///< Length) or not at all (returning 0 or -1 and setting 'errno' accordingly). - ///< \return Returns the number of bytes actually taken from Data, or -1 + ///< Returns the number of bytes actually taken from Data, or -1 ///< in case of an error. virtual int PlaySubtitle(const uchar *Data, int Length); ///< Plays the given data block as a subtitle. ///< Data points to exactly one complete PES packet of the given Length. ///< PlaySubtitle() shall process the packet either as a whole (returning ///< Length) or not at all (returning 0 or -1 and setting 'errno' accordingly). - ///< \return Returns the number of bytes actually taken from Data, or -1 + ///< Returns the number of bytes actually taken from Data, or -1 ///< in case of an error. virtual int PlayPesPacket(const uchar *Data, int Length, bool VideoOnly = false); ///< Plays the single PES packet in Data with the given Length. @@ -658,7 +658,7 @@ public: ///< Only the lower 32 bit of this value are actually used, since some ///< devices can't handle the msb correctly. virtual bool IsPlayingVideo(void) const { return isPlayingVideo; } - ///< \return Returns true if the currently attached player has delivered + ///< Returns true if the currently attached player has delivered ///< any video packets. virtual cRect CanScaleVideo(const cRect &Rect, int Alignment = taCenter) { return cRect::Null; } ///< Asks the output device whether it can scale the currently shown video in diff --git a/dvbdevice.h b/dvbdevice.h index d3218d2b..3674a615 100644 --- a/dvbdevice.h +++ b/dvbdevice.h @@ -4,7 +4,7 @@ * See the main source file 'vdr.c' for copyright information and * how to reach the author. * - * $Id: dvbdevice.h 2.27 2013/02/16 12:48:11 kls Exp $ + * $Id: dvbdevice.h 2.28 2013/02/16 15:20:17 kls Exp $ */ #ifndef __DVBDEVICE_H @@ -119,7 +119,7 @@ public: static bool Initialize(void); ///< Initializes the DVB devices. ///< Must be called before accessing any DVB functions. - ///< \return True if any devices are available. + ///< Returns true if any devices are available. protected: int adapter, frontend; private: diff --git a/pat.h b/pat.h index cffb5a28..08da051f 100644 --- a/pat.h +++ b/pat.h @@ -4,7 +4,7 @@ * See the main source file 'vdr.c' for copyright information and * how to reach the author. * - * $Id: pat.h 2.2 2011/12/04 13:38:17 kls Exp $ + * $Id: pat.h 2.3 2013/02/16 15:20:24 kls Exp $ */ #ifndef __PAT_H @@ -37,7 +37,7 @@ int GetCaDescriptors(int Source, int Transponder, int ServiceId, const int *CaSy ///< Copies all available CA descriptors for the given Source, Transponder and ServiceId ///< into the provided buffer at Data (at most BufSize bytes). Only those CA descriptors ///< are copied that match one of the given CA system IDs. - ///< \return Returns the number of bytes copied into Data (0 if no CA descriptors are + ///< Returns the number of bytes copied into Data (0 if no CA descriptors are ///< available), or -1 if BufSize was too small to hold all CA descriptors. ///< The return value tells whether these CA descriptors are to be used ///< for the individual streams. diff --git a/ringbuffer.h b/ringbuffer.h index 5b2eeb1c..1fff611c 100644 --- a/ringbuffer.h +++ b/ringbuffer.h @@ -4,7 +4,7 @@ * See the main source file 'vdr.c' for copyright information and * how to reach the author. * - * $Id: ringbuffer.h 2.4 2012/09/20 09:29:32 kls Exp $ + * $Id: ringbuffer.h 2.5 2013/02/16 15:20:37 kls Exp $ */ #ifndef __RINGBUFFER_H @@ -84,17 +84,17 @@ public: ///< Reads at most Max bytes from FileHandle and stores them in the ///< ring buffer. If Max is 0, reads as many bytes as possible. ///< Only one actual read() call is done. - ///< \return Returns the number of bytes actually read and stored, or + ///< Returns the number of bytes actually read and stored, or ///< an error value from the actual read() call. int Read(cUnbufferedFile *File, int Max = 0); ///< Like Read(int FileHandle, int Max), but reads from a cUnbufferedFile). int Put(const uchar *Data, int Count); ///< Puts at most Count bytes of Data into the ring buffer. - ///< \return Returns the number of bytes actually stored. + ///< Returns the number of bytes actually stored. uchar *Get(int &Count); ///< Gets data from the ring buffer. ///< The data will remain in the buffer until a call to Del() deletes it. - ///< \return Returns a pointer to the data, and stores the number of bytes + ///< Returns a pointer to the data, and stores the number of bytes ///< actually available in Count. If the returned pointer is NULL, Count has no meaning. void Del(int Count); ///< Deletes at most Count bytes from the ring buffer. diff --git a/thread.h b/thread.h index a08d40c9..d79e15ac 100644 --- a/thread.h +++ b/thread.h @@ -4,7 +4,7 @@ * See the main source file 'vdr.c' for copyright information and * how to reach the author. * - * $Id: thread.h 2.3 2012/10/04 12:15:39 kls Exp $ + * $Id: thread.h 2.4 2013/02/16 15:20:44 kls Exp $ */ #ifndef __THREAD_H @@ -31,7 +31,7 @@ public: bool Wait(int TimeoutMs = 0); ///< Waits at most TimeoutMs milliseconds for a call to Signal(), or ///< forever if TimeoutMs is 0. - ///< \return Returns true if Signal() has been called, false it the given + ///< Returns true if Signal() has been called, false it the given ///< timeout has expired. void Signal(void); ///< Signals a caller of Wait() that the condition it is waiting for is met.