From 54417569a94b2fc757c094a3826401b82c7d10fe Mon Sep 17 00:00:00 2001 From: hjk Date: Thu, 1 Oct 2020 09:24:00 +0200 Subject: [PATCH] ProjectExplorer: Documentation for some run configuration aspects Change-Id: I27568facbe0fa992b33c9d3b5b2588b486a85c63 Reviewed-by: Christian Kandeler --- .../runconfigurationaspects.cpp | 186 ++++++++++++++++++ .../projectexplorer/runconfigurationaspects.h | 2 +- 2 files changed, 187 insertions(+), 1 deletion(-) diff --git a/src/plugins/projectexplorer/runconfigurationaspects.cpp b/src/plugins/projectexplorer/runconfigurationaspects.cpp index 7c04274d999..33ecc6d0f33 100644 --- a/src/plugins/projectexplorer/runconfigurationaspects.cpp +++ b/src/plugins/projectexplorer/runconfigurationaspects.cpp @@ -52,6 +52,12 @@ namespace ProjectExplorer { /*! \class ProjectExplorer::TerminalAspect + \inmodule QtCreator + + \brief The TerminalAspect class lets a user specify that an executable + should be run in a separate terminal. + + The initial value is provided as a hint from the build systems. */ TerminalAspect::TerminalAspect() @@ -64,6 +70,9 @@ TerminalAspect::TerminalAspect() this, &TerminalAspect::calculateUseTerminal); } +/*! + \reimp +*/ void TerminalAspect::addToLayout(LayoutBuilder &builder) { QTC_CHECK(!m_checkBox); @@ -77,6 +86,9 @@ void TerminalAspect::addToLayout(LayoutBuilder &builder) }); } +/*! + \reimp +*/ void TerminalAspect::fromMap(const QVariantMap &map) { if (map.contains(settingsKey())) { @@ -90,6 +102,9 @@ void TerminalAspect::fromMap(const QVariantMap &map) m_checkBox->setChecked(m_useTerminal); } +/*! + \reimp +*/ void TerminalAspect::toMap(QVariantMap &data) const { if (m_userSet) @@ -114,17 +129,26 @@ void TerminalAspect::calculateUseTerminal() m_checkBox->setChecked(m_useTerminal); } +/*! + Returns whether a separate terminal should be used. +*/ bool TerminalAspect::useTerminal() const { return m_useTerminal; } +/*! + Sets the initial value to \a hint. +*/ void TerminalAspect::setUseTerminalHint(bool hint) { m_useTerminalHint = hint; calculateUseTerminal(); } +/*! + Returns whether the user set the value. +*/ bool TerminalAspect::isUserSet() const { return m_userSet; @@ -132,6 +156,10 @@ bool TerminalAspect::isUserSet() const /*! \class ProjectExplorer::WorkingDirectoryAspect + \inmodule QtCreator + + \brief The WorkingDirectoryAspect class lets the user specify a + working directory for running the executable. */ WorkingDirectoryAspect::WorkingDirectoryAspect() @@ -141,6 +169,9 @@ WorkingDirectoryAspect::WorkingDirectoryAspect() setSettingsKey("RunConfiguration.WorkingDirectory"); } +/*! + \reimp +*/ void WorkingDirectoryAspect::addToLayout(LayoutBuilder &builder) { QTC_CHECK(!m_chooser); @@ -187,6 +218,9 @@ void WorkingDirectoryAspect::resetPath() m_chooser->setFilePath(m_defaultWorkingDirectory); } +/*! + \reimp +*/ void WorkingDirectoryAspect::fromMap(const QVariantMap &map) { m_workingDirectory = FilePath::fromString(map.value(settingsKey()).toString()); @@ -199,6 +233,9 @@ void WorkingDirectoryAspect::fromMap(const QVariantMap &map) m_chooser->setFilePath(m_workingDirectory.isEmpty() ? m_defaultWorkingDirectory : m_workingDirectory); } +/*! + \reimp +*/ void WorkingDirectoryAspect::toMap(QVariantMap &data) const { const QString wd = m_workingDirectory == m_defaultWorkingDirectory @@ -207,6 +244,11 @@ void WorkingDirectoryAspect::toMap(QVariantMap &data) const data.insert(keyForDefaultWd(), m_defaultWorkingDirectory.toString()); } +/*! + Returns the selected directory. + + Macros in the value are expanded using \a expander. +*/ FilePath WorkingDirectoryAspect::workingDirectory(const MacroExpander *expander) const { const Utils::Environment env = m_envAspect ? m_envAspect->environment() @@ -222,11 +264,19 @@ FilePath WorkingDirectoryAspect::defaultWorkingDirectory() const return m_defaultWorkingDirectory; } +/*! + Returns the selected directory. + + Macros in the value are not expanded. +*/ FilePath WorkingDirectoryAspect::unexpandedWorkingDirectory() const { return m_workingDirectory; } +/*! + Sets the default value to \a defaultWorkingDir. +*/ void WorkingDirectoryAspect::setDefaultWorkingDirectory(const FilePath &defaultWorkingDir) { if (defaultWorkingDir == m_defaultWorkingDirectory) @@ -244,6 +294,9 @@ void WorkingDirectoryAspect::setDefaultWorkingDirectory(const FilePath &defaultW } } +/*! + \internal +*/ PathChooser *WorkingDirectoryAspect::pathChooser() const { return m_chooser; @@ -252,6 +305,10 @@ PathChooser *WorkingDirectoryAspect::pathChooser() const /*! \class ProjectExplorer::ArgumentsAspect + \inmodule QtCreator + + \brief The ArgumentsAspect class lets a user specify command line + arguments for an executable. */ ArgumentsAspect::ArgumentsAspect() @@ -262,6 +319,11 @@ ArgumentsAspect::ArgumentsAspect() m_labelText = tr("Command line arguments:"); } +/*! + Returns the main value of this aspect. + + Macros in the value are expanded using \a expander. +*/ QString ArgumentsAspect::arguments(const MacroExpander *expander) const { QTC_ASSERT(expander, return m_arguments); @@ -274,11 +336,19 @@ QString ArgumentsAspect::arguments(const MacroExpander *expander) const return expanded; } +/*! + Returns the main value of this aspect. + + Macros in the value are not expanded. +*/ QString ArgumentsAspect::unexpandedArguments() const { return m_arguments; } +/*! + Sets the main value of this aspect to \a arguments. +*/ void ArgumentsAspect::setArguments(const QString &arguments) { if (arguments != m_arguments) { @@ -291,16 +361,26 @@ void ArgumentsAspect::setArguments(const QString &arguments) m_multiLineChooser->setPlainText(arguments); } +/*! + Sets the displayes label text to \a labelText. +*/ void ArgumentsAspect::setLabelText(const QString &labelText) { m_labelText = labelText; } +/*! + Adds a button to reset the main value of this aspect to the value + computed by \a resetter. +*/ void ArgumentsAspect::setResetter(const std::function &resetter) { m_resetter = resetter; } +/*! + Resets the main value of this aspect. +*/ void ArgumentsAspect::resetArguments() { QString arguments; @@ -309,6 +389,9 @@ void ArgumentsAspect::resetArguments() setArguments(arguments); } +/*! + \reimp +*/ void ArgumentsAspect::fromMap(const QVariantMap &map) { QVariant args = map.value(settingsKey()); @@ -328,12 +411,18 @@ void ArgumentsAspect::fromMap(const QVariantMap &map) m_multiLineChooser->setPlainText(m_arguments); } +/*! + \reimp +*/ void ArgumentsAspect::toMap(QVariantMap &map) const { map.insert(settingsKey(), m_arguments); map.insert(settingsKey() + ".multi", m_multiLine); } +/*! + \internal +*/ QWidget *ArgumentsAspect::setupChooser() { if (m_multiLine) { @@ -354,6 +443,9 @@ QWidget *ArgumentsAspect::setupChooser() return m_chooser.data(); } +/*! + \reimp +*/ void ArgumentsAspect::addToLayout(LayoutBuilder &builder) { QTC_CHECK(!m_chooser && !m_multiLineChooser && !m_multiLineButton); @@ -404,6 +496,13 @@ void ArgumentsAspect::addToLayout(LayoutBuilder &builder) /*! \class ProjectExplorer::ExecutableAspect + \inmodule QtCreator + + \brief The ExecutableAspect class provides a building block to provide an + executable for a RunConfiguration. + + It combines a StringAspect that is typically updated automatically + by the build system's parsing results with an optional manual override. */ ExecutableAspect::ExecutableAspect() @@ -419,12 +518,21 @@ ExecutableAspect::ExecutableAspect() this, &ExecutableAspect::changed); } +/*! + \internal +*/ ExecutableAspect::~ExecutableAspect() { delete m_alternativeExecutable; m_alternativeExecutable = nullptr; } +/*! + Sets the display style of the paths to the default used on \a osType, + backslashes on Windows, forward slashes elsewhere. + + \sa Utils::StringAspect::setDisplayFilter() +*/ void ExecutableAspect::setExecutablePathStyle(OsType osType) { m_executable.setDisplayFilter([osType](const QString &pathName) { @@ -432,6 +540,11 @@ void ExecutableAspect::setExecutablePathStyle(OsType osType) }); } +/*! + Sets the settings key for history completion to \a historyCompleterKey. + + \sa Utils::PathChooser::setHistoryCompleter() +*/ void ExecutableAspect::setHistoryCompleter(const QString &historyCompleterKey) { m_executable.setHistoryCompleter(historyCompleterKey); @@ -439,6 +552,11 @@ void ExecutableAspect::setHistoryCompleter(const QString &historyCompleterKey) m_alternativeExecutable->setHistoryCompleter(historyCompleterKey); } +/*! + Sets the acceptable kind of path values to \a expectedKind. + + \sa Utils::PathChooser::setExpectedKind() +*/ void ExecutableAspect::setExpectedKind(const PathChooser::Kind expectedKind) { m_executable.setExpectedKind(expectedKind); @@ -446,6 +564,13 @@ void ExecutableAspect::setExpectedKind(const PathChooser::Kind expectedKind) m_alternativeExecutable->setExpectedKind(expectedKind); } +/*! + Sets the environment in which paths will be searched when the expected kind + of paths is chosen as PathChooser::Command or PathChooser::ExistingCommand + to \a env. + + \sa Utils::StringAspect::setEnvironment() +*/ void ExecutableAspect::setEnvironment(const Environment &env) { m_executable.setEnvironment(env); @@ -453,11 +578,25 @@ void ExecutableAspect::setEnvironment(const Environment &env) m_alternativeExecutable->setEnvironment(env); } +/*! + Sets the display \a style for aspect. + + \sa Utils::StringAspect::setDisplayStyle() +*/ void ExecutableAspect::setDisplayStyle(StringAspect::DisplayStyle style) { m_executable.setDisplayStyle(style); } +/*! + Makes an auto-detected executable overridable by the user. + + The \a overridingKey specifies the settings key for the user-provided executable, + the \a useOverridableKey the settings key for the fact that it + is actually overridden the user. + + \sa Utils::StringAspect::makeCheckable() +*/ void ExecutableAspect::makeOverridable(const QString &overridingKey, const QString &useOverridableKey) { QTC_ASSERT(!m_alternativeExecutable, return); @@ -471,6 +610,13 @@ void ExecutableAspect::makeOverridable(const QString &overridingKey, const QStri this, &ExecutableAspect::changed); } +/*! + Returns the path of the executable specified by this aspect. In case + the user selected a manual override this will be the value specified + by the user. + + \sa makeOverridable() + */ FilePath ExecutableAspect::executable() const { if (m_alternativeExecutable && m_alternativeExecutable->isChecked()) @@ -479,6 +625,9 @@ FilePath ExecutableAspect::executable() const return m_executable.filePath(); } +/*! + \reimp +*/ void ExecutableAspect::addToLayout(LayoutBuilder &builder) { m_executable.addToLayout(builder); @@ -486,28 +635,49 @@ void ExecutableAspect::addToLayout(LayoutBuilder &builder) m_alternativeExecutable->addToLayout(builder.finishRow()); } +/*! + Sets the label text for the main chooser to + \a labelText. + + \sa Utils::StringAspect::setLabelText() +*/ void ExecutableAspect::setLabelText(const QString &labelText) { m_executable.setLabelText(labelText); } +/*! + Sets the place holder text for the main chooser to + \a placeHolderText. + + \sa Utils::StringAspect::setPlaceHolderText() +*/ void ExecutableAspect::setPlaceHolderText(const QString &placeHolderText) { m_executable.setPlaceHolderText(placeHolderText); } +/*! + Sets the value of the main chooser to \a executable. +*/ void ExecutableAspect::setExecutable(const FilePath &executable) { m_executable.setFilePath(executable); m_executable.setShowToolTipOnLabel(true); } +/*! + Sets the settings key to \a key. +*/ void ExecutableAspect::setSettingsKey(const QString &key) { BaseAspect::setSettingsKey(key); m_executable.setSettingsKey(key); } +/*! + \reimp +*/ void ExecutableAspect::fromMap(const QVariantMap &map) { m_executable.fromMap(map); @@ -515,6 +685,9 @@ void ExecutableAspect::fromMap(const QVariantMap &map) m_alternativeExecutable->fromMap(map); } +/*! + \reimp +*/ void ExecutableAspect::toMap(QVariantMap &map) const { m_executable.toMap(map); @@ -525,6 +698,14 @@ void ExecutableAspect::toMap(QVariantMap &map) const /*! \class ProjectExplorer::UseLibraryPathsAspect + \inmodule QtCreator + + \brief The UseLibraryPathsAspect class lets a user specify whether build + library search paths should be added to the relevant environment + variables. + + This modifies DYLD_LIBRARY_PATH and DYLD_FRAMEWORK_PATH on Mac, PATH + on Windows and LD_LIBRARY_PATH everywhere else. */ UseLibraryPathsAspect::UseLibraryPathsAspect() @@ -543,8 +724,13 @@ UseLibraryPathsAspect::UseLibraryPathsAspect() setValue(ProjectExplorerPlugin::projectExplorerSettings().addLibraryPathsToRunEnv); } + /*! \class ProjectExplorer::UseDyldSuffixAspect + \inmodule QtCreator + + \brief The UseDyldSuffixAspect class lets a user specify whether the + DYLD_IMAGE_SUFFIX environment variable should be used on Mac. */ UseDyldSuffixAspect::UseDyldSuffixAspect() diff --git a/src/plugins/projectexplorer/runconfigurationaspects.h b/src/plugins/projectexplorer/runconfigurationaspects.h index 9999842f376..d76580698c6 100644 --- a/src/plugins/projectexplorer/runconfigurationaspects.h +++ b/src/plugins/projectexplorer/runconfigurationaspects.h @@ -81,7 +81,7 @@ public: Utils::FilePath workingDirectory(const Utils::MacroExpander *expander) const; Utils::FilePath defaultWorkingDirectory() const; Utils::FilePath unexpandedWorkingDirectory() const; - void setDefaultWorkingDirectory(const Utils::FilePath &defaultWorkingDir); + void setDefaultWorkingDirectory(const Utils::FilePath &defaultWorkingDirectory); Utils::PathChooser *pathChooser() const; private: