Commit 0d42728b authored by Volker Krause's avatar Volker Krause
Browse files

Update API docs for the application-side libraries a bit

parent 92134bac
PROJECT_NAME = "User Feedback Framework"
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
QT_AUTOBRIEF = YES
INHERIT_DOCS = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = YES
HIDE_IN_BODY_DOCS = YES
CASE_SENSE_NAMES = YES
SORT_MEMBERS_CTORS_1ST = YES
SORT_BRIEF_DOCS = YES
SHOW_USED_FILES = NO
SHOW_FILES = NO
WARN_NO_PARAMDOC = YES
INPUT = .
FILE_PATTERNS = *.h *.dox
EXCLUDE_PATTERNS = *_p.h
RECURSIVE = YES
GENERATE_HTML = YES
SOURCE_BROWSER = NO
SEARCHENGINE = NO
SERVER_BASED_SEARCH = NO
GENERATE_LATEX = NO
GENERATE_RTF = NO
ALPHABETICAL_INDEX = NO
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
CLASS_DIAGRAMS = YES
HAVE_DOT = YES
CLASS_GRAPH = YES
COLLABORATION_GRAPH = NO
GROUP_GRAPHS = NO
INCLUDE_GRAPH = NO
INCLUDED_BY_GRAPH = NO
DIRECTORY_GRAPH = NO
/*!
* @mainpage User Feedback Framework
* @section User Feedback
* Framework for collecting feedback from application users. This currently consists of two aspects:
* - Telemetry
* - Surveys
*
* @section Telemetry
* - Extensible set of data sources for telemetry.
* - Full control for the user on what data to contribute.
*
* @section Surveys
* - Distribute surveys and offer users to participate in them.
* - Allow the user to configure how often they want to participate in surveys.
*
*/
/*!
* @namespace UserFeedback
* Classes for integrating telemetry collection, survey targeting,
* and contribution encouragenemt and configuration into applications.
*/
......@@ -29,55 +29,81 @@ namespace UserFeedback {
class AbstractDataSourcePrivate;
/** Base class for data sources for statistical data. */
/*! Base class for data sources for statistical data. */
class USERFEEDBACKCORE_EXPORT AbstractDataSource
{
public:
virtual ~AbstractDataSource();
/** Returns the name of this data source. */
/*! Returns the name of this data source.
* This is used as identifier towards the server and should
* not be shown to the user.
* @see description()
* @returns The data source identifier configured on the feedback server.
*/
QString name() const;
/** Returns a human-readable, translated description of what
/*! Returns a human-readable, translated description of what
* this source provides.
* @see name()
* @returns A translated, human-readable string.
*/
virtual QString description() const = 0;
/** Implement this to return the data gathered by this source.
* Depending on the schema entry type for this source, the following
* formats are expected:
/*!
* Returns the data gathered by this source.
*
* Implement this to return the data provided by this source.
* One of the three following formats are expected:
* - scalar entries: QAssiciativeIterable
* - list entries: QSequentialIterable containing QAssociativeIterable
* - map entries: QAssiciativeIterable containing QAssociativeIterable
*
* The innermost QAssiciativeIterable must only contain one of the following
* base types (which has to match the corresponding schema entry element):
* - QString
* - int
* - double
* - bool
* - QString
* - int
* - double
* - bool
* All keys must be strings.
*
* @returns A variant complying with the above requirements.
*/
virtual QVariant data() = 0;
/** Load persistent state for this data source. */
/*! Load persistent state for this data source.
* @param settings A QSettings object opened in a dedicated group for loading
* persistent data.
*/
virtual void load(QSettings *settings);
/** Store persistent state for this data source. */
/*! Store persistent state for this data source.
* @param settings A QSettings object opened in a dedicated group for storing
* persistent data.
*/
virtual void store(QSettings *settings);
/** Returns which colleciton mode this data source belongs to. */
/*! Returns which colleciton mode this data source belongs to.
* @return The statistics collection category this source belongs to.
*/
Provider::StatisticsCollectionMode collectionMode() const;
/** Sets which colleciton mode this data source belongs to. */
/*! Sets which colleciton mode this data source belongs to.
* @param mode The data collection mode of this source.
*/
void setCollectionMode(Provider::StatisticsCollectionMode mode);
protected:
/** Create a new data source named @p name.
/*! Create a new data source named @p name.
* The name of the data source must match the corresponding
* product schema entry.
* @param name Must not be empty.
*/
explicit AbstractDataSource(const QString &name, AbstractDataSourcePrivate *dd = nullptr);
///@cond internal
class AbstractDataSourcePrivate* const d_ptr;
///@endcond
private:
Q_DECLARE_PRIVATE(AbstractDataSource)
......
......@@ -23,10 +23,14 @@
namespace UserFeedback {
/*! Data source for the application version.
* The application version is retrieved via QCoreApplication::applicationVersion.
*/
class USERFEEDBACKCORE_EXPORT ApplicationVersionSource : public AbstractDataSource
{
Q_DECLARE_TR_FUNCTIONS(ApplicationVersionSource)
public:
/*! Create a new application version source. */
ApplicationVersionSource();
QString description() const override;
QVariant data() override;
......
......@@ -22,15 +22,16 @@
namespace UserFeedback {
/** Reports information about the platform the application is running on.
/*! Reports information about the platform the application is running on.
* This includes two string data fields:
* - platformOS: the operating system name
* - platformVersion: the operating system or distribution version.
* - platform.os: the operating system name
* - platform.version: the operating system or distribution version.
*/
class USERFEEDBACKCORE_EXPORT PlatformInfoSource : public AbstractDataSource
{
Q_DECLARE_TR_FUNCTIONS(PlatformInfoSource)
public:
/*! Create a new platform information source. */
PlatformInfoSource();
QString description() const override;
QVariant data() override;
......
......@@ -25,7 +25,7 @@ namespace UserFeedback {
class PropertyRatioSourcePrivate;
/** Records the time ratio a given QObject property has a specific value.
/*! Records the time ratio a given QObject property has a specific value.
*
* An example use-case would be the usage ratio of a applications
* views/modes selected by a QTabWidget or QRadioButton.
......@@ -33,7 +33,7 @@ class PropertyRatioSourcePrivate;
class USERFEEDBACKCORE_EXPORT PropertyRatioSource : public AbstractDataSource
{
public:
/** Create a new property ratio data source.
/*! Create a new property ratio data source.
* @param obj the QObject of which a property should be monitored.
* @param propertyName The name of the property to monitor.
* This property must have a change notification signal. The value must have
......@@ -43,16 +43,20 @@ public:
*/
explicit PropertyRatioSource(QObject *obj, const char* propertyName, const QString &sampleName);
/** Map property value @value to @str for sending to the server.
/*! Map property value @p value to @p str for sending to the server.
* This is useful to map internal identifiers to portable and persistable values,
* such as turning pointers or indexes into meaningful descriptions.
* @param value The property value to map.
* @param str The string the property value @p value should be mapped to.
*/
void addValueMapping(const QVariant &value, const QString &str);
QString description() const override;
/** Set human-readable and translated description of the data provided by this source.
/*! Set human-readable and translated description of the data provided by this source.
* @note This must be set before adding this source, sources without description are
* discarded.
* @param desc The description.
*/
void setDescription(const QString &desc);
......
......@@ -30,44 +30,61 @@ class AbstractDataSource;
class ProviderPrivate;
class SurveyInfo;
/** The central object managing data sources and transmitting feedback to the server. */
/*! The central object managing data sources and transmitting feedback to the server. */
class USERFEEDBACKCORE_EXPORT Provider : public QObject
{
Q_OBJECT
/*! The interval in which the user accepts surveys.
* @c -1 indicates surveys are disabled.
* @see surveyInterval(), setSurveyInterval()
*/
Q_PROPERTY(int surveyInterval READ surveyInterval WRITE setSurveyInterval NOTIFY surveyIntervalChanged)
/*! The telemetry mode the user has configured.
* @see statisticsCollectionMode(), setStatisticsCollectionMode()
*/
Q_PROPERTY(StatisticsCollectionMode statisticsCollectionMode READ statisticsCollectionMode WRITE setStatisticsCollectionMode NOTIFY statisticsCollectionModeChanged)
public:
/*! Telemetry collection modes.
* Colleciton modes are inclusive, ie. higher modes always imply data from
* lower modes too.
*/
enum StatisticsCollectionMode {
NoStatistics,
BasicSystemInformation,
BasicUsageStatistics,
DetailedSystemInformation,
DetailedUsageStatistics,
NoStatistics, ///< Transmit no data at all.
BasicSystemInformation, ///< Transmit basic information about the system.
BasicUsageStatistics, ///< Transmit basic usage statistics.
DetailedSystemInformation, ///< Transmit detailed system information.
DetailedUsageStatistics, ///< Transmit detailed usage statistics.
CollectionModeCount = DetailedUsageStatistics
};
Q_ENUMS(StatisticsCollectionMode)
/*! Create a new feedback provider.
* @param parent The parent object.
*/
explicit Provider(QObject *parent = nullptr);
~Provider();
/** Set the product identifier.
/*! Set the product identifier.
* This is used to distinguish independent products on the same server.
* @param productId Unique product identifier, as configured on the feedback server.
*/
void setProductIdentifier(const QString &productId);
/** Set the feedback server URL. */
/*! Set the feedback server URL.
* @param url The URL of the feedback server.
*/
void setFeedbackServer(const QUrl &url);
/** Set the automatic submission interval. */
/*! Set the automatic submission interval. */
void setSubmissionInterval(int days);
/** Returns the current statistics collection mode. */
/*! Returns the current statistics collection mode. */
StatisticsCollectionMode statisticsCollectionMode() const;
/** Set which statistics should be submitted. */
/*! Set which statistics should be submitted. */
void setStatisticsCollectionMode(StatisticsCollectionMode mode);
/** Adds a data source for statistical data collection.
/*! Adds a data source for statistical data collection.
* @param source The data source to add. The Provider takes ownership of @p source.
* @param mode The statistics collection mode this source belongs to. Data is only
* send to the server for this source is a sufficiently high collection mode is configured
......@@ -75,56 +92,56 @@ public:
*/
void addDataSource(AbstractDataSource *source, StatisticsCollectionMode mode);
/** Returns all data sources that have been added to this provider.
/*! Returns all data sources that have been added to this provider.
* @see addDataSource
*/
QVector<AbstractDataSource*> dataSources() const;
/** Returns the minimum time between two surveys in days. */
/*! Returns the minimum time between two surveys in days. */
int surveyInterval() const;
/** Sets the minimum time in days between two surveys.
/*! Sets the minimum time in days between two surveys.
* @c -1 indicates no surveys should be requested.
*/
void setSurveyInterval(int days);
/** Marks the given survey as completed. This avoids getting further notification
/*! Marks the given survey as completed. This avoids getting further notification
* about the same survey.
*/
void setSurveyCompleted(const SurveyInfo &info);
/** Set the amount of application starts until the encouragement message should be shown. */
/*! Set the amount of application starts until the encouragement message should be shown. */
void setApplicationStartsUntilEncouragement(int starts);
/** Set the amount of usage time until the encouragement message should be shown. */
/*! Set the amount of usage time until the encouragement message should be shown. */
void setApplicationUsageTimeUntilEncouragement(int minutes);
/** Set the delay after application start for the earliest display of the encouragement message. */
/*! Set the delay after application start for the earliest display of the encouragement message. */
void setEncouragementDelay(int secs);
/** Sets the interval after the encouragement should be repeated.
/*! Sets the interval after the encouragement should be repeated.
* Encouragement messages are only repeated if no feedback options have been enabled.
* @param days Days between encouragement messages, 0 disables repeated encouragements.
*/
void setEncouragementInterval(int days);
public slots:
/** Manually submit currently recorded data. */
/*! Manually submit currently recorded data. */
void submit();
signals:
/** Emitted whenever there is a new survey available that can be presented
/*! Emitted whenever there is a new survey available that can be presented
* to the user.
*/
void surveyAvailable(const UserFeedback::SurveyInfo &survey);
/** Indicate that the encouragement notice should be shown. */
/*! Indicate that the encouragement notice should be shown. */
void showEncouragementMessage();
/** Emitted when the survey interval changed. */
/*! Emitted when the survey interval changed. */
void surveyIntervalChanged();
/** Emitted when the statistics collection mode has changed. */
/*! Emitted when the statistics collection mode has changed. */
void statisticsCollectionModeChanged();
private:
......
......@@ -23,10 +23,17 @@
namespace UserFeedback {
/*! Data source for information about connected displays.
* This provides as array of maps containing the following properties:
* - height: Height of the corresponding screen in pixel.
* - width: Width of the corresponding screen in pixel.
* - dpi: Dots per inch of the corresponding screen.
*/
class USERFEEDBACKCORE_EXPORT ScreenInfoSource : public AbstractDataSource
{
Q_DECLARE_TR_FUNCTIONS(ScreenInfoSource)
public:
/*! Create a new screen information source. */
ScreenInfoSource();
QString description() const override;
QVariant data() override;
......
......@@ -27,11 +27,12 @@ class Provider;
class ProviderPrivate;
class StartCountSourcePrivate;
/** Data source reporting the total amount of applications starts. */
/*! Data source reporting the total amount of applications starts. */
class USERFEEDBACKCORE_EXPORT StartCountSource : public AbstractDataSource
{
Q_DECLARE_TR_FUNCTIONS(StartCountSource)
public:
/*! Create a new start count data source. */
StartCountSource();
QString description() const override;
QVariant data() override;
......
......@@ -29,30 +29,36 @@ namespace UserFeedback {
class SurveyInfoData;
/** Information about a survey request. */
/*! Information about a survey request.
* This class is implicitly shared.
*/
class USERFEEDBACKCORE_EXPORT SurveyInfo
{
public:
/*! Create an empty, invalid survey request. */
SurveyInfo();
/*! Copy constructor. */
SurveyInfo(const SurveyInfo&);
~SurveyInfo();
/*! Assignment operator. */
SurveyInfo& operator=(const SurveyInfo&);
/** Returns @c true if this survey has all necessary information to actually execute it. */
/*! Returns @c true if this survey has all necessary information to actually execute it. */
bool isValid() const;
/** Internal unique id of the survey.
/*! Internal unique id of the survey.
* Used to locally check if a user has completed the survey already.
*/
int id() const;
void setId(int id);
/** The URL to the survey website. */
/*! The URL to the survey website. */
QUrl url() const;
void setUrl(const QUrl &url);
/** @internal */
///@cond internal
void setId(int id);
void setUrl(const QUrl &url);
static SurveyInfo fromJson(const QJsonObject &obj);
///@endcond
private:
QSharedDataPointer<SurveyInfoData> d;
};
......
......@@ -27,12 +27,13 @@ class Provider;
class ProviderPrivate;
class UsageTimeSourcePrivate;
/** Data source reporting the total usage time of the application. */
/*! Data source reporting the total usage time of the application. */
class USERFEEDBACKCORE_EXPORT UsageTimeSource : public AbstractDataSource
{
public:
Q_DECLARE_TR_FUNCTIONS(UsageTimeSource)
public:
/*! Create a new usage time data source. */
UsageTimeSource();
QString description() const override;
QVariant data() override;
......
......@@ -28,16 +28,26 @@ namespace UserFeedback {
class FeedbackConfigDialogPrivate;
class Provider;
/** Configure which feedback a user wants to provide. */
/*! Configure which feedback a user wants to provide.
*
* @see FeedbackConfigWidget
*/
class USERFEEDBACKWIDGETS_EXPORT FeedbackConfigDialog : public QDialog
{
Q_OBJECT
public:
/*! Create a new feedback configuration dialog.
* @param parent The parent widget.
*/
explicit FeedbackConfigDialog(QWidget *parent = nullptr);
~FeedbackConfigDialog();
/*! Set the feedback provider that this dialog configures. */
void setFeedbackProvider(UserFeedback::Provider *provider);
/*! Accpets the dialog and write changes made by the user to
* the feedback provider.
*/
void accept() override;
private:
......
......@@ -31,31 +31,40 @@ namespace UserFeedback {
class FeedbackConfigWidgetPrivate;
class Provider;
/**
/*!
* Configuration widget for telemetry and survey contributions.
*
* Use this rather than FeedbackConfigDialog if you want to embed the
* feedback configuration for example into an existing configuration
* dialog.
* @see FeedbackConfigDialog
*/
class USERFEEDBACKWIDGETS_EXPORT FeedbackConfigWidget : public QWidget
{
Q_OBJECT
public:
/*! Create a new feedback provider configuration widget.
* @param parent The parent widget.
*/
explicit FeedbackConfigWidget(QWidget *parent = nullptr);
~FeedbackConfigWidget();
/** Returns the feedback provider configured by this widget. */
/*! Returns the feedback provider configured by this widget. */
Provider* feedbackProvider() const;
/** Set the feedback provider that should be configured with this widget. */
/*! Set the feedback provider that should be configured with this widget. */
void setFeedbackProvider(Provider *provider);
/** Returns the telemetry level currently selected in the widget. */
/*! Returns the telemetry level currently selected in the widget. */
Provider::StatisticsCollectionMode statisticsCollectionMode() const;
/** Returns the survey interval currently selected in this widget. */
/*! Returns the survey interval currently selected in this widget. */
int surveyInterval() const;
protected:
///@cond internal
bool eventFilter(QObject *receiver, QEvent *event) override;
///@endcond
private:
Q_PRIVATE_SLOT(d, void telemetrySliderChanged())
......
......@@ -29,7 +29,7 @@ namespace UserFeedback {
class NotificationPopupPrivate;
class Provider;
/**
/*!
* Notification popup that overlays a small part of the application for
* encouraging contributions or inform about surveys.
*/
......@@ -37,7 +37,7 @@ class USERFEEDBACKWIDGETS_EXPORT NotificationPopup : public QWidget
{
Q_OBJECT
public:
/**
/*!
* Create a new notification popup.
* Do not put this widget into a layout.
* @param parent The parent widget. This must not be @c nullptr.
......@@ -45,14 +45,16 @@ public:
explicit NotificationPopup(QWidget *parent);
~NotificationPopup();
/**
/*!
* Set the feedback provider that is going to drive this notification popup.
*/
void setFeedbackProvider(Provider *provider);
protected:
///@cond internal
void keyReleaseEvent(QKeyEvent *event) override;
bool eventFilter(QObject *receiver, QEvent *event) override;
///@endcond
private:
Q_PRIVATE_SLOT(d, void showEncouragement())
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment