Improve documentation

This commit is contained in:
dokutan 2020-05-22 00:13:37 +02:00
parent a8b9535abf
commit ec1ad2818a
4 changed files with 38 additions and 36 deletions

View file

@ -58,7 +58,7 @@ PROJECT_LOGO =
# entered, it will be relative to the location where doxygen was started. If # entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used. # left blank the current directory will be used.
OUTPUT_DIRECTORY = OUTPUT_DIRECTORY = doxygen
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format and # directories (in 2 levels) under the output directory of each output format and
@ -823,7 +823,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched. # Note: If this tag is empty the current directory is searched.
INPUT = INPUT = include/
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

View file

@ -1,2 +1,4 @@
- [ ] Improve build method - [ ] Improve build method
- [ ] Installation on all supported platforms - [ ] Installation on all supported platforms
- [ ] Add more source documentation
- [ ] Rename class members to distinguish constants, functions and settings

View file

@ -36,6 +36,7 @@ class simple_ini_parser{
private: private:
/// Stores the key-value pairs
std::map< std::string, std::string > _ini_values; std::map< std::string, std::string > _ini_values;
public: public:
@ -50,7 +51,7 @@ class simple_ini_parser{
/** /**
* Get the value of the specified key. * Get the value of the specified key.
* \return The value of the specified key, or the specified default * \return The value of the specified key, or the specified default
* value * value if the key is unkwnown
*/ */
std::string get( std::string key, std::string default_value ); std::string get( std::string key, std::string default_value );

View file

@ -37,22 +37,25 @@
* The main class representing the M908 mouse. * The main class representing the M908 mouse.
* This class has member functions to open, close and apply settings to the mouse. * This class has member functions to open, close and apply settings to the mouse.
* *
* There are 3 main types of functions: * There are 4 main types of functions:
* - set_*: setters * - set_*: setters
* - get_*: getters * - get_*: getters
* - write_*: write the settings to the mouse * - write_*: write the settings to the mouse
* - read_*: read the sttings from the mouse
* *
* Therefore the general procedure when changing settings on the mouse is as follows: * Therefore the general procedure when changing settings on the mouse is as follows:
* 1. open_mouse() or open_mouse_bus_device() * 1. open_mouse() or open_mouse_bus_device()
* 2. set_* (this step only changes the internal state of the class) * 2. set_* (this step only changes the internal state of the class)
* 3. write_* (this step sends the internal state of the class to the mouse) * 3. write_* (this step sends the internal state of the class to the mouse)
* 4. close_mouse() * 4. close_mouse()
*
*
*/ */
class mouse_m908{ class mouse_m908{
public: public:
// constructor /// The default constructor. Sets the default settings.
mouse_m908(); mouse_m908();
@ -90,51 +93,50 @@ class mouse_m908{
//setter functions //setter functions
/** Set the currently active profile /// Set the currently active profile
*/
int set_profile( m908_profile profile ); int set_profile( m908_profile profile );
/** Set the scrollspeed for the specified profile /** \brief Set the scrollspeed for the specified profile
* \see _scrollspeed_min * \see _scrollspeed_min
* \see _scrollspeed_max * \see _scrollspeed_max
* \return 0 if successful, 1 if out of bounds * \return 0 if successful, 1 if out of bounds
*/ */
int set_scrollspeed( m908_profile profile, uint8_t speed ); int set_scrollspeed( m908_profile profile, uint8_t speed );
/** Set the led mode for the specified profile /** \brief Set the led mode for the specified profile
* \see m908_lightmode * \see m908_lightmode
* \return 0 if successful * \return 0 if successful
*/ */
int set_lightmode( m908_profile profile, m908_lightmode lightmode ); int set_lightmode( m908_profile profile, m908_lightmode lightmode );
/** Set the led color for the specified profile /** \brief Set the led color for the specified profile
* \param color color as {r, g, b} * \param color color as {r, g, b}
* \return 0 if successful * \return 0 if successful
*/ */
int set_color( m908_profile profile, std::array<uint8_t, 3> color ); int set_color( m908_profile profile, std::array<uint8_t, 3> color );
/** Set the led brightness for the specified profile /** \brief Set the led brightness for the specified profile
* \see _brightness_min * \see _brightness_min
* \see _brightness_max * \see _brightness_max
* \return 0 if successful, 1 if out of bounds * \return 0 if successful, 1 if out of bounds
*/ */
int set_brightness( m908_profile profile, uint8_t brightness ); int set_brightness( m908_profile profile, uint8_t brightness );
/** Set the led animation speed for the specified profile /** \brief Set the led animation speed for the specified profile
* \see _speed_min * \see _speed_min
* \see _speed_max * \see _speed_max
* \return 0 if successful, 1 if out of bounds * \return 0 if successful, 1 if out of bounds
*/ */
int set_speed( m908_profile profile, uint8_t speed ); int set_speed( m908_profile profile, uint8_t speed );
/** Enables/Disables a dpi level for the specified profile /** \brief Enables/Disables a dpi level for the specified profile
* \see _level_min * \see _level_min
* \see _level_max * \see _level_max
* \return 0 if successful, 1 if out of bounds * \return 0 if successful, 1 if out of bounds
*/ */
int set_dpi_enable( m908_profile profile, int level, bool enabled ); int set_dpi_enable( m908_profile profile, int level, bool enabled );
/** Set the value of a dpi level for the specified profile /** \brief Set the value of a dpi level for the specified profile
* \see _dpi_min * \see _dpi_min
* \see _dpi_max * \see _dpi_max
* \see _level_min * \see _level_min
@ -143,42 +145,42 @@ class mouse_m908{
*/ */
int set_dpi( m908_profile profile, int level, uint8_t dpi ); int set_dpi( m908_profile profile, int level, uint8_t dpi );
/** Set a mapping for a button for the specified profile /** \brief Set a mapping for a button for the specified profile
* \param mapping 4 bytes for the usb data packets * \param mapping 4 bytes for the usb data packets
* \return 0 if successful * \return 0 if successful
*/ */
int set_key_mapping( m908_profile profile, int key, std::array<uint8_t, 4> mapping ); int set_key_mapping( m908_profile profile, int key, std::array<uint8_t, 4> mapping );
/** Set a mapping for a button for the specified profile /** \brief Set a mapping for a button for the specified profile
* \param mapping button name (see keymap.md) * \param mapping button name (see keymap.md)
* \return 0 if successful, 1 if mapping is invalid * \return 0 if successful, 1 if mapping is invalid
*/ */
int set_key_mapping( m908_profile profile, int key, std::string mapping ); int set_key_mapping( m908_profile profile, int key, std::string mapping );
/** Set the USB poll rate for the specified profile /** \brief Set the USB poll rate for the specified profile
* \see m908_report_rate * \see m908_report_rate
* \return 0 if successful * \return 0 if successful
*/ */
int set_report_rate( m908_profile profile, m908_report_rate report_rate ); int set_report_rate( m908_profile profile, m908_report_rate report_rate );
/** Load the macro from the specified file into the specified slot /** \brief Load the macro from the specified file into the specified slot
* \param macro_number macro slot (1-15) * \param macro_number macro slot (1-15)
* \return 0 if successful * \return 0 if successful
*/ */
int set_macro( int macro_number, std::string file ); int set_macro( int macro_number, std::string file );
/** Load all macros from the specified .ini file /** \brief Load all macros from the specified .ini file
* \return 0 if successful * \return 0 if successful
*/ */
int set_all_macros( std::string file ); int set_all_macros( std::string file );
/** Set how many times the specified macro should be repeated /** \brief Set how many times the specified macro should be repeated
* \param macro_number macro slot (1-15) * \param macro_number macro slot (1-15)
* \return 0 if successful * \return 0 if successful
*/ */
int set_macro_repeat( int macro_number, uint8_t repeat ); int set_macro_repeat( int macro_number, uint8_t repeat );
/** Set whether to try to detach the kernel driver when opening the mouse /** \brief Set whether to try to detach the kernel driver when opening the mouse
*/ */
int set_detach_kernel_driver( bool detach_kernel_driver ); int set_detach_kernel_driver( bool detach_kernel_driver );
@ -218,22 +220,22 @@ class mouse_m908{
//writer functions (apply settings to mouse) //writer functions (apply settings to mouse)
/** Write the currently active profile to the mouse /** \brief Write the currently active profile to the mouse
* \return 0 if successful * \return 0 if successful
*/ */
int write_profile(); int write_profile();
/** Write the settings (leds, button mapping, dpi, etc.) to the mouse /** \brief Write the settings (leds, button mapping, dpi, etc.) to the mouse
* \return 0 if successful * \return 0 if successful
*/ */
int write_settings(); int write_settings();
/** Write a macro to the mouse /** \brief Write a macro to the mouse
* \return 0 if successful * \return 0 if successful
*/ */
int write_macro( int macro_number ); int write_macro( int macro_number );
/** Write the number of repeats for a macro to the mouse /** \brief Write the number of repeats for a macro to the mouse
* \return 0 if successful * \return 0 if successful
*/ */
int write_macro_repeat( int macro_number ); int write_macro_repeat( int macro_number );
@ -241,39 +243,36 @@ class mouse_m908{
//helper functions //helper functions
/** Init libusb and open the mouse by its USB VID and PID /** \brief Init libusb and open the mouse by its USB VID and PID
* \return 0 if successful * \return 0 if successful
*/ */
int open_mouse(); int open_mouse();
/** Init libusb and open the mouse by the USB bus and device adress /** \brief Init libusb and open the mouse by the USB bus and device adress
* \return 0 if successful * \return 0 if successful
*/ */
int open_mouse_bus_device( uint8_t bus, uint8_t device ); int open_mouse_bus_device( uint8_t bus, uint8_t device );
/** Close the mouse and libusb /** \brief Close the mouse and libusb
* \return 0 if successful (always at the moment) * \return 0 if successful (always at the moment)
*/ */
int close_mouse(); int close_mouse();
/** /// Print the current configuration in .ini format to output
* Print the current configuration in .ini format to output
*/
int print_settings( std::ostream& output ); int print_settings( std::ostream& output );
//reader functions (get settings from the mouse) //reader functions (get settings from the mouse)
/** /// Read the settings and print the raw data to output
* Read the settings and print the raw data to output
*/
int dump_settings( std::ostream& output ); int dump_settings( std::ostream& output );
/** /**
* Read the settings and print the configuration in .ini format to output. * \brief Read the settings and print the configuration in .ini format to output.
* This does not alter the internal settings of the mouse_m908 class. * This does not alter the internal settings of the mouse_m908 class.
*/ */
int read_and_print_settings( std::ostream& output ); int read_and_print_settings( std::ostream& output );
/** /**
* Read the settings and print the configuration in .ini format to output. * \brief Read the settings and print the configuration in .ini format to output.
* This updates the internal settings of the mouse_m908 class. * This updates the internal settings of the mouse_m908 class.
*/ */
int read_settings(); int read_settings();