Doc: edit debugger API docs

Remove \brief commands from function descriptions.
Use QDoc commands for notes and lists.
Write GDB in all caps.
Fix punctuation and style and grammar issues.

Change-Id: I7f5bf0f53ad643eb4e2981c0d4e39c453dff5558
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@digia.com>

src/plugins/debugger/cdb/cdbparsehelpers.cpp

@@ -460,7 +460,7 @@ QDebug operator<<(QDebug s, const WinException &e)
 /*!
     \fn DisassemblerLines parseCdbDisassembler(const QList<QByteArray> &a)
 
-    \brief Parse CDB disassembler output into DisassemblerLines (with helpers)
+    Parses CDB disassembler output into DisassemblerLines (with helpers).
 
     Expected options (prepend source file line):
     \code

src/plugins/debugger/debuggerplugin.cpp

@@ -156,7 +156,7 @@
 
     \brief The DebuggerEngine class is the base class of a debugger engine.
 
-    Note: the Debugger process itself and any helper processes like
+    \note The Debugger process itself and any helper processes like
     gdbserver are referred to as 'Engine', whereas the debugged process
     is referred to as 'Inferior'.
 
@@ -327,9 +327,11 @@ sg1: }
 
     GdbEngine specific startup. All happens in EngineSetupRequested state:
 
-    Transitions marked by '---' are done in the individual adapters.
+    \list
+        \li Transitions marked by '---' are done in the individual adapters.
 
-    Transitions marked by '+-+' are done in the GdbEngine.
+        \li Transitions marked by '+-+' are done in the GdbEngine.
+    \endlist
 
     \code
                   GdbEngine::setupEngine()

src/plugins/debugger/debuggersourcepathmappingwidget.cpp

@@ -193,7 +193,7 @@ void SourcePathMappingModel::setTarget(int row, const QString &t)
     \brief The DebuggerSourcePathMappingWidget class is a widget for maintaining
     a set of source path mappings for the debugger.
 
-    Path mappings to be applied using source path substitution in gdb.
+    Path mappings to be applied using source path substitution in GDB.
 */
 
 DebuggerSourcePathMappingWidget::DebuggerSourcePathMappingWidget(QWidget *parent) :

src/plugins/debugger/debuggertooltipmanager.cpp

@@ -568,7 +568,7 @@ QDebug operator<<(QDebug d, const DebuggerToolTipContext &c)
     (defaultModel) and displays that.
 
     It is associated with file name and position with functionality to
-    acquire and release the engine: When the debugger stops at a file, all
+    acquire and release the engine. When the debugger stops at a file, all
     matching tooltips acquire the engine, that is, display the engine data.
     When continuing or switching away from the frame, the tooltips release the
     engine, that is, store the data internally and keep displaying them
@@ -1086,11 +1086,11 @@ QString DebuggerToolTipWidget::clipboardContents() const
     listens on editor scroll and main window move
     events and takes care of repositioning the tooltips.
 
-    Listens to editor change and mode change. In debug mode, if there tooltips
+    Listens to editor change and mode change. In debug mode, if there are tooltips
-    for the current editor (by file name), position and show them.
+    for the current editor (by file name), positions and shows them.
 
     In addition, listens on state change and stack frame completed signals
-    of the engine. If a stack frame is completed, have all matching tooltips
+    of the engine. If a stack frame is completed, has all matching tooltips
     (by file name and function) acquire the engine, others release.
 */
 

src/plugins/debugger/gdb/gdbengine.cpp

@@ -2412,9 +2412,9 @@ void GdbEngine::handleExecuteReturn(const GdbResponse &response)
 }
 
 /*!
-    \brief Discard the results of all pending watch-updating commands.
+    Discards the results of all pending watch-updating commands.
 
-    This method is called at the beginning of all step/next/finish etc.
+    This method is called at the beginning of all step, next, finish, and so on,
     debugger functions.
     If non-watch-updating commands with call-backs are still in the pipe,
     it will complain.

src/plugins/debugger/memoryview.cpp

@@ -43,7 +43,7 @@ namespace Internal {
     \class Debugger::Internal::MemoryView
     \brief The MemoryView class is a base class for memory view tool windows.
 
-    Small tool-window that stays on top and displays a chunk of memory
+    This class is a small tool-window that stays on top and displays a chunk of memory
     based on the widget provided by the Bin editor plugin.
 
     Provides static functionality for handling a Bin Editor Widget

src/plugins/debugger/watchwindow.cpp

@@ -237,7 +237,7 @@ static int memberVariableRecursion(const QAbstractItemModel *model,
 typedef QList<MemoryMarkup> MemoryMarkupList;
 
 /*!
-    \brief Creates markup for a variable in the memory view.
+    Creates markup for a variable in the memory view.
 
     Marks the visible children with alternating colors in the parent, that is, for
     \code