From 96b09ded9fedb0a97bab468124e1aeafdda93b43 Mon Sep 17 00:00:00 2001 From: John Ralls Date: Wed, 10 Nov 2021 18:01:55 -0800 Subject: [PATCH] Doxygen documentation for new options classes. --- gnucash/gnome-utils/dialog-options.hpp | 44 +++++++++++ gnucash/gnome/business-options-gnome.h | 9 +++ libgnucash/app-utils/gnc-option-date.hpp | 91 +++++++++++++++++++++- libgnucash/app-utils/gnc-option-impl.hpp | 88 +++++++++------------ libgnucash/app-utils/gnc-option-uitype.hpp | 15 ++++ libgnucash/app-utils/gnc-option.hpp | 38 ++++++++- libgnucash/app-utils/gnc-optiondb-impl.hpp | 18 +++++ libgnucash/app-utils/gnc-optiondb.h | 35 ++++++++- libgnucash/app-utils/gnc-optiondb.hpp | 9 +++ 9 files changed, 292 insertions(+), 55 deletions(-) diff --git a/gnucash/gnome-utils/dialog-options.hpp b/gnucash/gnome-utils/dialog-options.hpp index c2fb570c24..b0101c23d3 100644 --- a/gnucash/gnome-utils/dialog-options.hpp +++ b/gnucash/gnome-utils/dialog-options.hpp @@ -3,6 +3,7 @@ * Copyright (C) 1998-2000 Linas Vepstas * * Copyright (c) 2006 David Hampton * * Copyright (c) 2011 Robert Fewell * + * Copyright 2019-2021 John Ralls * * * * This program is free software; you can redistribute it and/or * * modify it under the terms of the GNU General Public License as * @@ -21,6 +22,10 @@ * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * * Boston, MA 02110-1301, USA gnu@gnu.org * \********************************************************************/ +/** @addtogroup GUI + @{ */ +/** @addtogroup GuiOptions Options Dialog + @{ */ #ifndef GNC_DIALOG_OPTIONS_HPP_ #define GNC_DIALOG_OPTIONS_HPP_ @@ -31,18 +36,49 @@ #include #include "dialog-options.h" +/** @fn WidgetCreateFunc + * Function pointer for per-option-type GtkWidget constructors. + * @param option The option to create an element for. + * @param page_box The option dialog page's layout grid + * @param name_label A GtkLabel to attach to the widget + * @param documentation The string to use for the tooltip. + * @param enclosing The parent widget + * @param packed Whether the widget will be packed into an eventbox. + * @return pointer to the widget. + */ + typedef GtkWidget* (*WidgetCreateFunc)(GncOption&, GtkGrid*, GtkLabel*, char*, GtkWidget**, bool*); +/** @class GncOptionUIFactory + * Factory class that keeps track of which GncOptionValueType needs which + * WidgetCreateFunc and calls the appropriate one when required. + */ class GncOptionUIFactory { public: +/** Register a WidgetCreateFunc + * @param type The UI type + * @param func The function to register + */ static void set_func(GncOptionUIType type, WidgetCreateFunc func); +/** Create a widget + * @param option The option for which to create the widget + * @param page The Option dialog page in which to insert the widget + * @param name The label to attach to the widget + * @param description The text for the widget's tooltip + * @param enclosing The widget's parent + * @param packed Whether the widget will be packed into an eventbox. + * @return pointer to the created widget. + */ static GtkWidget* create(GncOption&, GtkGrid*, GtkLabel*, char*, GtkWidget**, bool*); private: static std::vector s_registry; }; +/** class GncOptionGtkUIItem + * Gtk-specific Interface class for Option Widget + */ class GncOptionGtkUIItem : public GncOptionUIItem { public: @@ -50,7 +86,9 @@ public: GncOptionGtkUIItem(const GncOptionGtkUIItem& item); GncOptionGtkUIItem(GncOptionGtkUIItem&&) = default; virtual ~GncOptionGtkUIItem() override; +/** Control wether the widget is sensitive */ virtual void set_selectable(bool) const noexcept override; +/** Clear the data from the widget. */ void clear_ui_item() override; void set_widget(GtkWidget* widget); virtual GtkWidget* const get_widget() const { return m_widget; } @@ -68,6 +106,10 @@ template GtkWidget* create_option_widget(GncOption& option, GtkGrid*, GtkLabel*, char*, GtkWidget**, bool*); +/** Templated cast to convert various QofInstance subtype ptrs into QofInstance* + * to placate the C++ type system. QofInstance is a GObject hierarchy so the + * usual C++ type substitution doesn't work. + */ template inline const QofInstance* qof_instance_cast(Instance inst) { @@ -76,3 +118,5 @@ qof_instance_cast(Instance inst) } #endif // GNC_DIALOG_OPTIONS_HPP_ +/** @} + @} */ diff --git a/gnucash/gnome/business-options-gnome.h b/gnucash/gnome/business-options-gnome.h index 47d518f225..fb454c0f83 100644 --- a/gnucash/gnome/business-options-gnome.h +++ b/gnucash/gnome/business-options-gnome.h @@ -21,10 +21,19 @@ * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * Boston, MA 02110-1301, USA gnu@gnu.org */ +/** @addtogroup GUI + @{ */ +/** @addtogroup GuiOptions Options Dialog + @{ */ #ifndef GNC_BUSINESS_OPTIONS_H_ #define GNC_BUSINESS_OPTIONS_H_ +/** + * Set up the business and counters pages in the File Preferences dialog. + */ void gnc_business_options_gnome_initialize (void); #endif /* GNC_BUSINESS_OPTIONS_H_ */ +/** @} + @} */ diff --git a/libgnucash/app-utils/gnc-option-date.hpp b/libgnucash/app-utils/gnc-option-date.hpp index 82f963d607..395dee3aa1 100644 --- a/libgnucash/app-utils/gnc-option-date.hpp +++ b/libgnucash/app-utils/gnc-option-date.hpp @@ -20,7 +20,14 @@ * Boston, MA 02110-1301, USA gnu@gnu.org * * * \********************************************************************/ - +/** @addtogroup Engine + @{ */ +/** @addtogroup Options + @{ */ +/** @file gnc-option-date.hpp + @brief Relative date enumeration and manipulation functions. + @author Copyright 2019-2021 John Ralls +*/ #ifndef GNC_OPTION_DATE_HPP_ #define GNC_OPTION_DATE_HPP_ @@ -78,14 +85,96 @@ constexpr unsigned relative_date_periods = using RelativeDatePeriodVec = std::vector; +/** + * Report whether the relative date represents a period offset to today's date + * rather than the beginning or end of a date range. For example ONE_MONTH_AGO + * will be made concrete as the same day as today in the previous month. + * + * @param period The Relative Date Period to check. + * @return true if the date is stand-alone. + */ bool gnc_relative_date_is_single(RelativeDatePeriod); + +/** + * Report whether the relative date represents the beginning of a date + * range. For example START_LAST_MONTH is the beginning of a range. + * + * @param period The Relative Date Period to check. + * @return true if the date is the beginning of a date range + */ bool gnc_relative_date_is_starting(RelativeDatePeriod); + +/** + * Report whether the relative date represents the end of a date range. For + * example END_LAST_MONTH is the end of a range. + * + * @param period The Relative Date Period to check. + * @return true if the date is the end of a date range. + */ bool gnc_relative_date_is_ending(RelativeDatePeriod); + +/** + * Provide the string representation of a relative date for persisting the + * value. This string is not localizable. + * + * @param period The relative date period. + * @return A constant string or nullptr if the period is ABSOLUTE. The string's + * lifetime will be that of the Relative Date Period. It must not be freed and + * should be copied if the period might be destroyed before the using code is + * finished. + */ const char* gnc_relative_date_storage_string(RelativeDatePeriod); + +/** + * Provide the string representation of a relative date for displaying + * value to a user. This string is not localizable. + * + * @param period The relative date period. + * @return A constant string or nullptr if the period is ABSOLUTE. The string's + * lifetime will be that of the Relative Date Period. It must not be freed and + * should be copied if the period might be destroyed before the using code is + * finished. + */ const char* gnc_relative_date_display_string(RelativeDatePeriod); + +/** + * Provide the description of a relative date. This string is localizable. + * + * @param period The relative date period. + * @return A constant string or nullptr if the period is ABSOLUTE. The string's + * lifetime will be that of the Relative Date Period. It must not be freed and + * should be copied if the period might be destroyed before the using code is + * finished. + */ const char* gnc_relative_date_description(RelativeDatePeriod); + +/** + * Convert a relative date storage string back to a RelativeDatePeriod value. + * + * @param A string representation obtained from + * gnc_relative_date_storage_string. + * @return A RelativeDatePeriod value. + */ RelativeDatePeriod gnc_relative_date_from_storage_string(const char*); + +/** + * Convert a RelativeDatePeriod value to a concrete time64 by applying the value to the current time. For example if it is now 3:15:42 PM local time 3 June, calling this with a period RelativeDatePeriod::ONE_WEEK_AHEAD will return a time64 representing 3:15:42 PM local time 10 June of this year. + * + * @param period The relative date period to use to calculate the concrete date. + * @return a time64. + */ time64 gnc_relative_date_to_time64(RelativeDatePeriod); + +/** + * Add the display string to the provided std::ostream. + * + * @param stream the std::ostream to which to write the period value + * @param period the period value to write + * @return A reference to stream so that the operator can be chained. + */ std::ostream& operator<<(std::ostream&, const RelativeDatePeriod); #endif //GNC_OPTION_DATE_HPP_ + +/** @} + @} */ diff --git a/libgnucash/app-utils/gnc-option-impl.hpp b/libgnucash/app-utils/gnc-option-impl.hpp index f3294bd1e5..f71be8f0c5 100644 --- a/libgnucash/app-utils/gnc-option-impl.hpp +++ b/libgnucash/app-utils/gnc-option-impl.hpp @@ -21,6 +21,15 @@ * * \********************************************************************/ +/** @addtogroup Engine + @{ */ +/** @addtogroup Options + @{ */ +/** @file gnc-option-impl.hpp + @brief Implementation templates and specializtions for GncOption values. + Objecte created by these templates are wrapped by the GncOption variant. + @author Copyright 2019-2021 John Ralls +*/ #ifndef GNC_OPTION_IMPL_HPP_ #define GNC_OPTION_IMPL_HPP_ @@ -46,51 +55,6 @@ extern "C" #include "gnc-option-uitype.hpp" -/* - * Unused base class to document the structure of the current Scheme option - * vector, re-expressed in C++. The comment-numbers on the right indicate which - * item in the Scheme vector each item implements. - * - * Not everything here needs to be implemented, nor will it necessarily be - * implemented the same way. For example, part of the purpose of this redesign - * is to convert from saving options as strings of Scheme code to some form of - * key-value pair in the book options, so generate_restore_form() will likely be - * supplanted with save_to_book(). - -template -class GncOptionBase -{ -public: - virtual ~GncOption = default; - virtual ValueType get_value() const = 0; //5 - virtual ValueType get_default_value() = 0; - virtual SCM get_SCM_value() = 0; - virtual SCM get_SCM_default_value() const = 0; //7 - virtual void set_value(ValueType) = 0; //6 -// generate_restore_form outputs a Scheme expression (a "form") that finds an -// option and sets it to the current value. e.g.: -//(let ((option (gnc:lookup-option options -// "Display" -// "Amount"))) -// ((lambda (option) (if option ((gnc:option-setter option) 'none))) option)) -// it uses gnc:value->string to generate the "'none" (or whatever the option's -// value would be as input to the scheme interpreter). - - virtual std::string generate_restore_form(); //8 - virtual void save_to_book(QofBook*) const noexcept; //9 - virtual void read_from_book(QofBook*); //10 - virtual std::vector get_option_strings(); //15 - virtual set_changed_callback(std::function); //14 -protected: - const std::string m_section; //0 - const std::string m_name; //1 - const std::string m_sort_tag; //2 - const std::type_info m_kvp_type; //3 - const std::string m_doc_string; //4 - std::function m_changed_callback; //Part of the make-option closure - std::functionm_option_widget_changed_callback; //16 -}; -*/ static const char* commodity_scm_intro{"'(commodity-scm "}; #ifndef SWIG @@ -98,6 +62,12 @@ size_t constexpr classifier_size_max{50}; size_t constexpr sort_tag_size_max{10}; #endif +/** @struct OptionClassifier + * This class is the parent of all option implmentations. It contains the + * elements that the optiondb uses to retrieve option values and that the + * options dialog determines on which tab to place the option, in what order, + * and what string to display as a tooltip. + */ struct OptionClassifier { std::string m_section; @@ -112,6 +82,9 @@ struct OptionClassifier auto constexpr size_t_max = std::numeric_limits::max(); #endif +/** @class GncOptionValue + * The generic option-value class. Most option types can use this template. + */ template class GncOptionValue : public OptionClassifier { @@ -167,6 +140,12 @@ private: ValueType m_default_value; }; +/** class GncOptionValidatedValue + * Validated values have an additional member function, provided as a + * constructor argument, that checks value parameters for some property before + * setting the object's value member. If the function returns false a + * std::invalid_argument exception is thrown. + */ template class GncOptionValidatedValue : public OptionClassifier { @@ -353,7 +332,7 @@ operator>> >(std::istream& iss, } #endif // SWIG -/** +/** @class GncOptionRangeValue * Used for numeric ranges and plot sizes. */ @@ -461,7 +440,8 @@ using GncMultichoiceOptionEntry = std::tuple; using GncMultichoiceOptionChoices = std::vector; -/** Multichoice options have a vector of valid options +/** @class GncOptionMultichoiceValue + * Multichoice options have a vector of valid options * (GncMultichoiceOptionChoices) and validate the selection as being one of * those values. The value is the index of the selected item in the vector. The * tuple contains three strings, a key, and a display @@ -731,7 +711,7 @@ using GncOptionAccountList = std::vector; using GncOptionAccountTypeList = std::vector; -/** Account options +/** @class GncOptionAccountListValue * * Set one or more accounts on which to report, optionally restricted to certain * account types. Many calls to make-account-list-option will pass a get-default @@ -853,6 +833,10 @@ operator>> (std::istream& iss, return iss; } +/* @class GncOptionAccountSelValue + * Like GncOptionAccountListValue but contains only a single account. + */ + class GncOptionAccountSelValue : public OptionClassifier { public: @@ -936,8 +920,8 @@ operator>> (std::istream& iss, return iss; } -/** Date options - * A legal date value is a pair of either and a RelativeDatePeriod, the absolute +/** @class GncOptionDateValue + * A legal date value is a pair of either a RelativeDatePeriod, the absolute * flag and a time64, or for legacy purposes the absolute flag and a timespec. */ /* @@ -1076,7 +1060,7 @@ operator>> (std::istream& iss, return opt.in_stream(iss); } -/** QofQuery Options - */ #endif //GNC_OPTION_IMPL_HPP_ +/**@} + @} */ diff --git a/libgnucash/app-utils/gnc-option-uitype.hpp b/libgnucash/app-utils/gnc-option-uitype.hpp index 22098bb72b..76c6e48e03 100644 --- a/libgnucash/app-utils/gnc-option-uitype.hpp +++ b/libgnucash/app-utils/gnc-option-uitype.hpp @@ -23,6 +23,19 @@ #ifndef GNC_OPTION_UITYPE_HPP__ #define GNC_OPTION_UITYPE_HPP__ +/** @addtogroup Engine + @{ */ +/** @addtogroup Options + @{ */ +/** @file gnc-option-uitype.hpp + @brief OptionUITypes + @author Copyright 2019-2021 John Ralls +*/ + +/** @enum GncOptionUIType + * Used by GncOptionClassifier to indicate to dialog-options what control + * should be displayed for the option. + */ enum class GncOptionUIType : unsigned int { INTERNAL, @@ -59,3 +72,5 @@ enum class GncOptionUIType : unsigned int }; #endif // GNC_OPTION_UITYPE_H__ +/** @} + @} */ diff --git a/libgnucash/app-utils/gnc-option.hpp b/libgnucash/app-utils/gnc-option.hpp index 9374959e2b..0913f6d6d5 100644 --- a/libgnucash/app-utils/gnc-option.hpp +++ b/libgnucash/app-utils/gnc-option.hpp @@ -20,6 +20,15 @@ * Boston, MA 02110-1301, USA gnu@gnu.org * * * \********************************************************************/ +/** @addtogroup Engine + @{ */ +/** @addtogroup Options + @{ */ + +/** @file gnc-option.hpp + @brief C++ Public interface for individual options. + @author Copyright 2020-2021 John Ralls +*/ #ifndef GNC_OPTION_HPP_ #define GNC_OPTION_HPP_ @@ -110,6 +119,12 @@ enum class GncOptionMultichoiceKeyType NUMBER, }; +/** @class GncOption + * @brief Represents the public interface for an option. + * Polymorphism is provided by a std::variant member containing GncOptionValue + * types. +*/ + class GncOption { public: @@ -144,14 +159,24 @@ public: void set_option_from_ui_item(); void make_internal(); bool is_changed() const noexcept; +/** @returns false unless m_option contains a GncOptionMultiselectValue or + * GncOptionAccountListValue for which multiple selections have been enabled. + */ bool is_multiselect() const noexcept; +/** Implemented only for GncOptionNumericRange */ template void get_limits(ValueType&, ValueType&, ValueType&) const noexcept; +/** Not implemented for GncOptionValue. */ template bool validate(ValueType value) const; +/** Implemented only for GncOptionMultiselectValue. */ std::size_t num_permissible_values() const; +/** Implemented only for GncOptionMultiselectValue. */ std::size_t permissible_value_index(const char* value) const; +/** Implemented only for GncOptionMultiselectValue. */ const char* permissible_value(std::size_t index) const; +/** Implemented only for GncOptionMultiselectValue. */ const char* permissible_value_name(std::size_t index) const; +/** Implemented only for GncOptionAccountListValue. */ GList* account_type_list() const noexcept; bool is_alternate() const noexcept; void set_alternate(bool) noexcept; @@ -202,6 +227,11 @@ output_color_value(std::ostream& oss, const std::string& value) return oss; } +/** + * Free function wrapping GncOption's constructor. The type of GncOptionValue to + * create is determined from the UI type. Some GncOptionValue types require more + * parameters for their constructors and can't be created with this function. + */ template GncOption* gnc_make_option(const char* section, const char* name, const char* key, const char* doc_string, @@ -210,9 +240,15 @@ gnc_make_option(const char* section, const char* name, return new GncOption(section, name, key, doc_string, value, ui_type); } -/* To work around SWIG_Guile's typedef of SCM to unsigned long: */ +/** + * Free function wrapping GncOption's constructor using an SCM value. + * To work around SWIG_Guile's typedef of SCM to unsigned long + */ GncOption* gnc_make_SCM_option(const char* section, const char* name, const char* key, const char* doc_string, SCM value, GncOptionUIType ui_type); #endif //GNC_OPTION_HPP_ + +/** @} + @} */ diff --git a/libgnucash/app-utils/gnc-optiondb-impl.hpp b/libgnucash/app-utils/gnc-optiondb-impl.hpp index 5fa8114702..5083531d95 100644 --- a/libgnucash/app-utils/gnc-optiondb-impl.hpp +++ b/libgnucash/app-utils/gnc-optiondb-impl.hpp @@ -20,6 +20,14 @@ * Boston, MA 02110-1301, USA gnu@gnu.org * * * \********************************************************************/ +/** @addtogroup Engine + @{ */ +/** @addtogroup Options + @{ */ +/** @file gnc-optiondb-impl.hpp + @brief Implementation details for GncOptionDB. + @author Copyright 2019-2021 John Ralls +*/ #ifndef GNC_OPTIONDB_P_HPP_ #define GNC_OPTIONDB_P_HPP_ @@ -45,6 +53,10 @@ extern "C" using GncOptionVec = std::vector; +/** class GncOptionSection + * The upper-level classification implmentation. Contains the options for a + * section; sections are displayed as separate tabs on the option dialog. + */ class GncOptionSection { std::string m_name; @@ -90,6 +102,10 @@ struct GncOptionDBCallback using GncCallbackVec = std::vector; +/** @class GncOptionDB + * Holds all of the options for a book, report, or stylesheet, organized by + * GncOptionSections. + */ class GncOptionDB { public: @@ -171,3 +187,5 @@ private: #endif // GNC_OPTIONDB_P_HPP_ +/** @} + @} */ diff --git a/libgnucash/app-utils/gnc-optiondb.h b/libgnucash/app-utils/gnc-optiondb.h index d2fe65540c..f828536e98 100644 --- a/libgnucash/app-utils/gnc-optiondb.h +++ b/libgnucash/app-utils/gnc-optiondb.h @@ -20,7 +20,37 @@ * Boston, MA 02110-1301, USA gnu@gnu.org * * * \********************************************************************/ - +/** @addtogroup Engine + @{ */ +/** @addtogroup Options + GnuCash Options System for Book, Report, and Stylesheet Options. + + The GnuCash Options System supports two somewhat different purposes: + - File properties, such as business information and whether to use automatic + trading accounts. + + - Report options for configuring and customizing reports. Most report + options are user-configurable through a report options dialog but some are + used as a way of passing enumeration values between the scheme modules + that generate the report. + + The options system is centered on an options database or optiondb. A + separate optionsdb is created and instantiated for every use, so the book + gets one at the beginning of the session with its values loaded from KVP, + and every report gets one when the report is run, as do report stylesheets + when they are edited. Customized report and stylesheet options are saved as + Scheme code fragments in files in the user's GnuCash Config directory. + + @note + Persistence via text scheme code is a security vulnerability as it + enables an attacker to make GnuCash execute arbitrary code. The Guile + interpreter affords full system access with at least the user's privileges. + + @{ */ +/** @file gnc-optiondb.h + @brief C public interface for the Options Database. + @author Copyright 2019-2021 John Ralls +*/ #ifndef GNC_OPTIONDB_H_ #define GNC_OPTIONDB_H_ @@ -179,3 +209,6 @@ void gnc_option_db_set_scm_value(GncOptionDB*, const char*, } #endif #endif //GNC_OPTIONDB_H_ + +/** @} + @} */ diff --git a/libgnucash/app-utils/gnc-optiondb.hpp b/libgnucash/app-utils/gnc-optiondb.hpp index 002efa9e3b..b274155ad6 100644 --- a/libgnucash/app-utils/gnc-optiondb.hpp +++ b/libgnucash/app-utils/gnc-optiondb.hpp @@ -20,6 +20,15 @@ * Boston, MA 02110-1301, USA gnu@gnu.org * * * \********************************************************************/ +/** @addtogroup Engine + @{ */ +/** @addtogroup Options + @{ */ +/** @file gnc-optiondb.hpp + * @brief The primary C++ interface to options for books, reports, and + * stylesheets. + * @author Copyright 2019-2021 John Ralls +*/ #ifndef GNC_OPTIONDB_HPP_ #define GNC_OPTIONDB_HPP_