Some documentation for the VME profiler

Change-Id: Ifa36166e803e81484c6a96c732b72f0ee2412c28
Reviewed-by: Simon Hausmann <simon.hausmann@digia.com>

1 files changed, 76 insertions, 0 deletions

diff --git a/src/qml/debugger/qqmlprofilerservice.cpp b/src/qml/debugger/qqmlprofilerservice.cpp
index 9daa6acd5e..b83de937c6 100644
--- a/src/qml/debugger/qqmlprofilerservice.cpp
+++ b/src/qml/debugger/qqmlprofilerservice.cpp
@@ -425,6 +425,10 @@ void QQmlProfilerService::messageReceived(const QByteArray &message)
     m_initializeCondition.wakeAll();
 }
 
+/*!
+ * \brief QQmlVmeProfiler::Data::clear Reset to defaults
+ * Reset the profiling data to defaults.
+ */
 void QQmlVmeProfiler::Data::clear()
 {
     url = QUrl();
@@ -433,6 +437,16 @@ void QQmlVmeProfiler::Data::clear()
     typeName = QString();
 }
 
+/*!
+ * \brief QQmlVmeProfiler::start Start profiler and set data
+ * \param url URL of file being executed
+ * \param line Curent line in file
+ * \param column Current column in file
+ * \param typeName Type of object be created
+ * Stops the profiler previously running in the foreground if there is one, then starts a
+ * new one and sets it up with the data given.
+ * Preconditions: Profiling must be enabled.
+ */
 void QQmlVmeProfiler::start(const QUrl &url, int line, int column, const QString &typeName)
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -443,6 +457,12 @@ void QQmlVmeProfiler::start(const QUrl &url, int line, int column, const QString
     }
 }
 
+/*!
+ * \brief QQmlVmeProfiler::start Start profiler without data
+ * Clears the current range data, then stops the profiler previously running in the
+ * foreground if any, then starts a new one.
+ * Preconditions: Profiling must be enabled.
+ */
 void QQmlVmeProfiler::start()
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -452,6 +472,10 @@ void QQmlVmeProfiler::start()
     }
 }
 
+/*!
+ * \brief QQmlVmeProfiler::switchRange Switch foreground profilers
+ * Stops the current profiler if any, and starts a new one.
+ */
 void QQmlVmeProfiler::switchRange()
 {
     if (running)
@@ -461,6 +485,14 @@ void QQmlVmeProfiler::switchRange()
     QQmlProfilerService::instance->startRange(QQmlProfilerService::Creating);
 }
 
+/*!
+ * \brief QQmlVmeProfiler::updateLocation Update current location information
+ * \param url URL of file being executed
+ * \param line line Curent line in file
+ * \param column column Current column in file
+ * Updates the current profiler's location information.
+ * Preconditions: Profiling must be enabled and a profiler must be running in the foreground.
+ */
 void QQmlVmeProfiler::updateLocation(const QUrl &url, int line, int column)
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -474,6 +506,12 @@ void QQmlVmeProfiler::updateLocation(const QUrl &url, int line, int column)
     }
 }
 
+/*!
+ * \brief QQmlVmeProfiler::updateTypeName Update current type information
+ * \param typeName Type of object being created
+ * Updates the current profiler's type information.
+ * Preconditions: Profiling must be enabled and a profiler must be running in the foreground.
+ */
 void QQmlVmeProfiler::updateTypeName(const QString &typeName)
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -484,6 +522,13 @@ void QQmlVmeProfiler::updateTypeName(const QString &typeName)
     }
 }
 
+/*!
+ * \brief QQmlVmeProfiler::pop Pops a paused profiler from the stack and restarts it
+ * Stops the currently running profiler, if any, then retrieves an old one from the stack
+ * of paused profilers and starts that.
+ * Preconditions: Profiling must be enabled and there must be at least one profiler on the
+ * stack.
+ */
 void QQmlVmeProfiler::pop()
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -497,6 +542,13 @@ void QQmlVmeProfiler::pop()
     }
 }
 
+/*!
+ * \brief QQmlVmeProfiler::push Pushes the currently running profiler on the stack.
+ * Pushes the currently running profiler on the stack of paused profilers. Note: The profiler
+ * isn't paused here. That's a separate step. If it's never paused, but pop()'ed later that
+ * won't do any harm, though.
+ * Preconditions: Profiling must be enabled and a profiler must be running in the foreground.
+ */
 void QQmlVmeProfiler::push()
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -505,6 +557,12 @@ void QQmlVmeProfiler::push()
         ranges.push(currentRange);
 }
 
+/*!
+ * \brief QQmlVmeProfiler::clear Stop all running profilers and clear all data.
+ * Stops the currently running (foreground and background) profilers and removes all saved
+ * data about paused profilers.
+ * Precondtions: Profiling must be enabled.
+ */
 void QQmlVmeProfiler::clear()
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -518,6 +576,10 @@ void QQmlVmeProfiler::clear()
     }
 }
 
+/*!
+ * \brief QQmlVmeProfiler::stop Stop profiler running in the foreground, if any.
+ * Precondition: Profiling must be enabled.
+ */
 void QQmlVmeProfiler::stop()
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -528,6 +590,13 @@ void QQmlVmeProfiler::stop()
     }
 }
 
+/*!
+ * \brief QQmlVmeProfiler::background Push the current profiler to the background.
+ * Push the profiler currently running in the foreground to the background so that it
+ * won't be stopped by stop() or start(). There can be multiple profilers in the background.
+ * You can retrieve them in reverse order by calling foreground().
+ * Precondition: Profiling must be enabled and a profiler must be running in the foreground.
+ */
 void QQmlVmeProfiler::background()
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");
@@ -538,6 +607,13 @@ void QQmlVmeProfiler::background()
     }
 }
 
+/*!
+ * \brief QQmlVmeProfiler::foreground Retrieve a profiler from the background
+ * Stop the profiler currently running in the foreground, if any and put the next profiler
+ * from the background in its place.
+ * Preconditions: Profiling must be enabled and there must be at least one profiler in the
+ * background.
+ */
 void QQmlVmeProfiler::foreground()
 {
     Q_ASSERT_X(enabled, Q_FUNC_INFO, "method called although profiler is not enabled.");