From 0acf541d2c77bfec37c344a4f4cfb789bf15be96 Mon Sep 17 00:00:00 2001 From: bruceperens Date: Thu, 16 Jan 2014 05:27:55 +0000 Subject: [PATCH] Add all of the doxygen documentation, fix lots of code nits. git-svn-id: https://svn.code.sf.net/p/freetel/code@1356 01035d8c-6547-0410-b346-abe4f91aad63 --- freedv-server/CMakeLists.txt | 2 + freedv-server/examples/.gitignore | 0 freedv-server/source/audio_sink.cpp | 21 ++--- freedv-server/source/big_main.cpp | 20 ++--- freedv-server/source/blank_panel.cpp | 3 + freedv-server/source/codec_noop.cpp | 5 +- freedv-server/source/driver_manager.cpp | 5 +- freedv-server/source/drivers.h | 115 ++++++++++++++++++++---- freedv-server/source/keying_sink.cpp | 8 +- freedv-server/source/modem_noop.cpp | 9 +- freedv-server/source/ptt_constant.cpp | 3 +- freedv-server/source/text_constant.cpp | 3 +- freedv-server/source/tone.cpp | 3 +- 13 files changed, 149 insertions(+), 48 deletions(-) create mode 100644 freedv-server/examples/.gitignore diff --git a/freedv-server/CMakeLists.txt b/freedv-server/CMakeLists.txt index a01d54fe..bc630b44 100644 --- a/freedv-server/CMakeLists.txt +++ b/freedv-server/CMakeLists.txt @@ -30,6 +30,8 @@ set(CMAKE_DISABLE_SOURCE_CHANGES ON) set(CMAKE_DISABLE_IN_SOURCE_BUILD ON) project(freedv-server) +include(cmake/UseDoxygen.cmake) + # Parameters are stored as .txt files in the parameters/ subdirectory. # They use semicolon to separate arguments, because this is what cmake uses # in its list type. Thus, parameters/version.txt looks like this: diff --git a/freedv-server/examples/.gitignore b/freedv-server/examples/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/freedv-server/source/audio_sink.cpp b/freedv-server/source/audio_sink.cpp index 0410d578..0394bd69 100644 --- a/freedv-server/source/audio_sink.cpp +++ b/freedv-server/source/audio_sink.cpp @@ -1,22 +1,24 @@ #include "drivers.h" -// Audio output "sink", discards the audio, for testing. - namespace FreeDV { + /// Audio output "sink", discards the audio, for testing. class AudioSink : public AudioOutput { public: + /// Instantiate the audio sink. AudioSink(const char * parameters); ~AudioSink(); - // Get the current audio level, normalized to the range of 0.0 to 1.0. - float level(); + /// Get the current audio level, normalized to the range of 0.0 to 1.0. + virtual float + level(); - // Set the current audio level within the range of 0.0 to 1.0. - float level(float value); + /// Set the current audio level within the range of 0.0 to 1.0. + virtual void + level(float value); - // Write audio into the "short" type. - std::size_t + /// Write audio into the "short" type. + virtual std::size_t write16(const int16_t * array, std::size_t length); }; @@ -35,10 +37,9 @@ namespace FreeDV { return 0; } - float + void AudioSink::level(float value) { - return value; } // Write audio into the "short" type. diff --git a/freedv-server/source/big_main.cpp b/freedv-server/source/big_main.cpp index 59cd0fe1..7e22f45e 100644 --- a/freedv-server/source/big_main.cpp +++ b/freedv-server/source/big_main.cpp @@ -1,14 +1,13 @@ #ifndef NO_INITIALIZERS -/* - * This is the main program for applications that are not space-limited. - * Any application that is space limited should have its own main that - * wires drivers to the Interfaces class without using DriverManager. - * Thus, you can get rid of all of the STL template use, etc. - * - * For the sake of correctness and optimization, I have written whatever I - * can to be without side-effects, a style inherited from functional programming. - * Thus, the excessive use of "const". - Bruce - */ +/// This is the main program for applications that are not space-limited. +/// Any application that is space limited should have its own main that +/// wires drivers to the Interfaces class without using DriverManager. +/// Thus, you can get rid of all of the STL template use, etc. +/// +/// For the sake of correctness and optimization, I have written whatever I +/// can to be without side-effects, a style inherited from functional +/// programming. Thus, the excessive use of "const". - Bruce + #include #include #include @@ -20,6 +19,7 @@ using namespace std; namespace FreeDV { + /// Run the main loop of the program, this is called after arguments are set. extern int run(struct Interfaces *); } using namespace FreeDV; diff --git a/freedv-server/source/blank_panel.cpp b/freedv-server/source/blank_panel.cpp index b2da0171..81cb7a25 100644 --- a/freedv-server/source/blank_panel.cpp +++ b/freedv-server/source/blank_panel.cpp @@ -1,8 +1,11 @@ #include "drivers.h" namespace FreeDV { + /// This is control-less GUI driver, for testing. class BlankPanel : public UserInterface { public: + + /// Instantiate the blank panel GUI driver. BlankPanel(const char * parameter, Interfaces * interfaces); virtual ~BlankPanel(); diff --git a/freedv-server/source/codec_noop.cpp b/freedv-server/source/codec_noop.cpp index 74dab64e..3ad767f8 100644 --- a/freedv-server/source/codec_noop.cpp +++ b/freedv-server/source/codec_noop.cpp @@ -1,10 +1,11 @@ #include "drivers.h" -// Codec "no-op", just copies its input to its output. For plain SSB voice, and for testing. namespace FreeDV { + /// Codec "no-op", just copies its input to its output. For plain SSB voice, and for testing. class CodecNoOp : public Codec { public: + /// Instantiate the no-op codec. CodecNoOp(const char *); ~CodecNoOp(); @@ -14,6 +15,8 @@ namespace FreeDV { /// \param i The array of audio samples to be encoded, in an array /// of signed 16-bit integers. /// \param o The encoded data, in an array of unsigned 8-bit integers. + /// \param length The number of audio samples to be encoded. + /// This must be a multiple of frame_size(). /// \return The number of uint8_t elements in the encoded array. virtual std::size_t encode16(const int16_t * i, uint8_t * o, \ diff --git a/freedv-server/source/driver_manager.cpp b/freedv-server/source/driver_manager.cpp index f6442267..324e5e43 100644 --- a/freedv-server/source/driver_manager.cpp +++ b/freedv-server/source/driver_manager.cpp @@ -188,7 +188,9 @@ namespace FreeDV { user_interface_drivers[driver] = creator; } - // This has to be a function to get around the static initalization order problem. + /// Automatic initializer for the driver manager. + /// This has to be a function to get around the static initalization order + /// problem. DriverManager & init_driver_manager() { @@ -196,6 +198,7 @@ namespace FreeDV { return manager; } + /// Global reference to the driver manager instance. DriverManager & driver_manager = init_driver_manager(); } #endif diff --git a/freedv-server/source/drivers.h b/freedv-server/source/drivers.h index 3f91c7b7..53f368f4 100644 --- a/freedv-server/source/drivers.h +++ b/freedv-server/source/drivers.h @@ -64,7 +64,7 @@ namespace FreeDV { /// Set the current audio level. /// The value must be within the range of 0.0 to 1.0. - virtual float level(float value) = 0; + virtual void level(float value) = 0; /// Write audio from an array of the signed 16-bit integer type. virtual std::size_t @@ -88,6 +88,7 @@ namespace FreeDV { /// \param i The array of audio samples to be encoded, in an array /// of signed 16-bit integers. /// \param o The encoded data, in an array of unsigned 8-bit integers. + /// \param length The number of audio samples to be encoded. /// \return The number of uint8_t elements in the encoded array. virtual std::size_t encode16(const int16_t * i, uint8_t * o, \ @@ -140,7 +141,11 @@ namespace FreeDV { /// This is a simplification on all of the values that POSIX /// poll() can return. Events that aren't read or write are mapped /// to one of those. + + /// File being monitored is readable or has read error. const unsigned int Read = 1; + + /// File being monitored is writable or has write error. const unsigned int Write = 2; /// Create an event handler instance. @@ -150,6 +155,9 @@ namespace FreeDV { } virtual ~EventHandler() = 0; + /// If set_exit() has been called, return true once. + /// \return True if set_exit has been called. The next and subsequent + /// calls will return false until set_exit() is called again. inline bool get_exit() { if ( do_exit ) { do_exit = false; @@ -167,6 +175,7 @@ namespace FreeDV { /// implementation of loop() must not call iterate(). void iterate(); + /// Cause get_exit() to return true the next time it is called. inline void set_exit() { do_exit = true; } public: /// Return true if this object is owned by a UserInterface object. @@ -240,17 +249,21 @@ namespace FreeDV { /// Push-to-talk input driver. class PTTInput { private: + /// Coroutine to be called when the sense of the push-to-talk switch + /// changes. void (*callback)(bool); protected: - // The driver calls this member to inform FreeDV that the PTT switch value has changed. - // the value is true for key-down, false for key-up. + /// The driver calls this member to inform FreeDV that the PTT switch + /// sense has changed. The value is true for key-down, + /// false for key-up. + /// \param value True for key-down, false for key-up. void changed(bool value); /// Create a push-to-talk switch instance. /// \param parameters Driver-specific configuration parameters. - PTTInput(const char * parameters); + virtual ~PTTInput() = 0; public: @@ -263,13 +276,15 @@ namespace FreeDV { virtual bool const captive() const; + /// Set the function that will be called when the push-to-talk input + /// changes its value. void set_callback(void (*value)(bool)); }; /// Driver for the text message source function. class TextInput { protected: - // The driver calls this member to set the text. + /// The child class calls this member in its parent to set the text. void set(const char * text); @@ -326,17 +341,29 @@ namespace FreeDV { { } + /// The voice codec in use. Codec * codec; + /// The event loop handler. This is specific to a GUI, or POSIX. EventHandler * event_handler; + /// The output used to key the transmitter. Keying * keying_output; + /// The audio output which drives the loudspeaker or headphone. AudioOutput * loudspeaker; + /// The audio input from the microphone. AudioInput * microphone; + /// The softmodem. Modem * modem; + /// The PTT input that indicates the transmission is to be digital audio. PTTInput * ptt_input_digital; + /// The PTT input that indicates the transmission is to be SSB. PTTInput * ptt_input_ssb; + /// The text to be transmitted in our text side-channel. TextInput * text; + /// The audio output that drives the transmitter. AudioOutput * transmitter; + /// The audio input from the receiver. AudioInput * receiver; + /// The user interface driver. Used for GUIs. UserInterface * user_interface; }; } @@ -361,32 +388,90 @@ namespace FreeDV { std::map text_input_drivers; std::map user_interface_drivers; public: + + /// Initialize the driver manager. DriverManager(); ~DriverManager(); - void print(std::ostream &); + /// Print the available drivers to the argument stream. + /// \param stream A reference to an instance of ostream on which the + /// information is to be printed. + void print(std::ostream & stream); - AudioInput * audio_input(const char * driver, const char * parameter); - AudioOutput * audio_output(const char * driver, const char * parameter); - Codec * codec(const char * driver, const char * parameter); - Keying * keying_output(const char * driver, const char * parameter); - Modem * modem(const char * driver, const char * parameter); - PTTInput * ptt_input(const char * driver, const char * parameter); - TextInput * text_input(const char * driver, const char * parameter); - UserInterface * user_interface(const char * driver, const char * parameter, Interfaces * interfaces); + /// Instantiate an AudioInput driver. + /// \param driver The name of the driver. + /// \param parameters Driver-specific configuration parameters. + AudioInput * audio_input(const char * driver, const char * parameters); + /// Instantiate an AudioOutput driver. + /// \param driver The name of the driver. + /// \param parameters Driver-specific configuration parameters. + AudioOutput * audio_output(const char * driver, const char * parameters); + /// Instantiate a Codec. + /// \param driver The name of the driver. + /// \param parameters Driver-specific configuration parameters. + Codec * codec(const char * driver, const char * parameters); + /// Instantiate a Keying driver. + /// \param driver The name of the driver. + /// \param parameters Driver-specific configuration parameters. + Keying * keying_output(const char * driver, const char * parameters); + /// Instantiate a softmodem. + /// \param driver The name of the driver. + /// \param parameters Driver-specific configuration parameters. + Modem * modem(const char * driver, const char * parameters); + /// Instantiate a PTT input driver. + /// \param driver The name of the driver. + /// \param parameters Driver-specific configuration parameters. + PTTInput * ptt_input(const char * driver, const char * parameters); + /// Instantiate a text input driver. + /// \param driver The name of the driver. + /// \param parameters Driver-specific configuration parameters. + TextInput * text_input(const char * driver, const char * parameters); + /// Instantiate a user interface driver. + /// \param driver The name of the driver. + /// \param parameters Driver-specific configuration parameters. + /// \param interfaces Interfaces object used to hold all of the + /// current device driver instances. + UserInterface * user_interface(const char * driver, const char * parameters, Interfaces * interfaces); + /// Register an audio input driver. + /// \param driver The name of the driver. + /// \param creator The coroutine that will instantiate the driver. void register_audio_input(const char * driver, AudioInput * (*creator)(const char *)); + /// Register an audio input driver. + /// \param driver The name of the driver. + /// \param creator The coroutine that will instantiate the driver. void register_audio_output(const char * driver, AudioOutput * (*creator)(const char *)); + /// Register an audio input driver. + /// \param driver The name of the driver. + /// \param creator The coroutine that will instantiate the driver. void register_codec(const char * driver, Codec * (*creator)(const char *)); + /// Register an audio input driver. + /// \param driver The name of the driver. + /// \param creator The coroutine that will instantiate the driver. void register_keying_output(const char * driver, Keying * (*creator)(const char *)); + /// Register an audio input driver. + /// \param driver The name of the driver. + /// \param creator The coroutine that will instantiate the driver. void register_modem(const char * driver, Modem * (*creator)(const char *)); + /// Register an audio input driver. + /// \param driver The name of the driver. + /// \param creator The coroutine that will instantiate the driver. void register_ptt_input(const char * driver, PTTInput * (*creator)(const char *)); + /// Register an audio input driver. + /// \param driver The name of the driver. + /// \param creator The coroutine that will instantiate the driver. void register_text_input(const char * driver, TextInput * (*creator)(const char *)); + /// Register an audio input driver. + /// \param driver The name of the driver. + /// \param creator The coroutine that will instantiate the driver. void register_user_interface(const char * driver, UserInterface * (*creator)(const char *, Interfaces *)); }; + /// Global reference to the driver manager. extern DriverManager & driver_manager; - // This version has to be called from static initializers. + + /// Return a reference to the driver manager instance. + /// This is a function because it is called in static initializers. extern DriverManager & init_driver_manager(); #endif } diff --git a/freedv-server/source/keying_sink.cpp b/freedv-server/source/keying_sink.cpp index 8f8cf9f4..ad6bfa5f 100644 --- a/freedv-server/source/keying_sink.cpp +++ b/freedv-server/source/keying_sink.cpp @@ -1,14 +1,16 @@ #include "drivers.h" -// Keying output "sink", doesn't key anything. For testing or use with VOX. namespace FreeDV { + /// Keying output "sink", doesn't key anything. For testing or use with VOX. class KeyingSink : public Keying { public: + /// Instantiate keying sink driver. KeyingSink(const char *); - ~KeyingSink(); + virtual ~KeyingSink(); - void key(bool value); + virtual void + key(bool value); }; diff --git a/freedv-server/source/modem_noop.cpp b/freedv-server/source/modem_noop.cpp index 4ce4dc25..ceea431d 100644 --- a/freedv-server/source/modem_noop.cpp +++ b/freedv-server/source/modem_noop.cpp @@ -1,15 +1,14 @@ #include "drivers.h" -// Modem "no-op", just copies its input to its output. For plain SSB voice, and for testing. namespace FreeDV { + /// Modem "no-op", just copies its input to its output. + /// For plain SSB voice, and for testing. class ModemNoOp : public Modem { public: + /// Instantiate the no-op modem. ModemNoOp(const char *); - ~ModemNoOp(); - - void key(bool value); - + virtual ~ModemNoOp(); }; ModemNoOp::ModemNoOp(const char * parameters) diff --git a/freedv-server/source/ptt_constant.cpp b/freedv-server/source/ptt_constant.cpp index 4f3ac4c6..82eae6ff 100644 --- a/freedv-server/source/ptt_constant.cpp +++ b/freedv-server/source/ptt_constant.cpp @@ -1,9 +1,10 @@ #include "drivers.h" -// PTT driver that is constant transmit or constant receive. For testing. namespace FreeDV { + /// PTT driver that is constant transmit or constant receive. For testing. class PTTConstant : public PTTInput { public: + /// Instantiate push-to-talk source with constant input, for testing. PTTConstant(const char * parameters); virtual ~PTTConstant(); diff --git a/freedv-server/source/text_constant.cpp b/freedv-server/source/text_constant.cpp index ea5fa14e..d493bc6d 100644 --- a/freedv-server/source/text_constant.cpp +++ b/freedv-server/source/text_constant.cpp @@ -1,9 +1,10 @@ #include "drivers.h" -// This is a test driver that provides tones. namespace FreeDV { + /// This driver provides constant text. class TextConstant : public TextInput { public: + /// Instantiate the constant text driver. TextConstant(const char * parameter); virtual ~TextConstant(); diff --git a/freedv-server/source/tone.cpp b/freedv-server/source/tone.cpp index 46431518..1412b703 100644 --- a/freedv-server/source/tone.cpp +++ b/freedv-server/source/tone.cpp @@ -1,9 +1,10 @@ #include "drivers.h" -// This is a test driver that provides tones. namespace FreeDV { + /// This is a test driver that provides tones. class Tone : public AudioInput { public: + /// Instantiate the tone driver. Tone(const char * parameter); virtual ~Tone(); -- 2.25.1