Doc: edit vcsbase docs

Remove \brief for \enum and \fn commands.
Use standard wording. Edit for style and grammar.

Change-Id: I338567241ddc7f90feaaf058dcd4dc9afdb8ca93
Reviewed-by: Tobias Hunger <tobias.hunger@digia.com>

4 files changed, 26 insertions, 21 deletions

diff --git a/src/plugins/vcsbase/corelistener.cpp b/src/plugins/vcsbase/corelistener.cpp
index 017d95b6f5..e1252e7975 100644
--- a/src/plugins/vcsbase/corelistener.cpp
+++ b/src/plugins/vcsbase/corelistener.cpp
@@ -35,7 +35,7 @@
 
     \brief The CoreListener class catches the closing of a submit editor.
 
-    Catch the closing of a submit editor to trigger the submit.
+    Catches the closing of a submit editor to trigger the submit.
     One instance of this class exists, connected to the instances
     of VcsBasePlugin, which dispatch if the editor kind matches theirs
     (which is why the approach of passing the bool result was chosen).
diff --git a/src/plugins/vcsbase/submitfieldwidget.cpp b/src/plugins/vcsbase/submitfieldwidget.cpp
index a0df616cf0..4dd0052198 100644
--- a/src/plugins/vcsbase/submitfieldwidget.cpp
+++ b/src/plugins/vcsbase/submitfieldwidget.cpp
@@ -57,10 +57,10 @@ static void inline setComboBlocked(QComboBox *cb, int index)
     fields like "reviewed-by:",
     "signed-off-by:".
 
-    It displays them in a vertical row of combo/line edit fields
+    The widget displays the fields in a vertical row of combo boxes or line edit fields
     that is modeled after the target address controls of mail clients.
-    When choosing a different field in the combo, a new row is opened if text
-    has been entered for the current field. Optionally, a "Browse..." button and
+    When choosing a different field in the combo box, a new row is opened if text
+    has been entered for the current field. Optionally, a \gui Browse button and
     completer can be added.
 */
 
diff --git a/src/plugins/vcsbase/submitfilemodel.cpp b/src/plugins/vcsbase/submitfilemodel.cpp
index 2bc7f75feb..c7c8c1b118 100644
--- a/src/plugins/vcsbase/submitfilemodel.cpp
+++ b/src/plugins/vcsbase/submitfilemodel.cpp
@@ -163,7 +163,7 @@ unsigned int SubmitFileModel::filterFiles(const QStringList &filter)
 
 /*! Updates user selections from \a source model.
  *
- *  Assumption: Both model are sorted with the same order, and there
+ *  Assumes that both models are sorted with the same order, and there
  *              are no duplicate entries.
  */
 void SubmitFileModel::updateSelections(SubmitFileModel *source)
diff --git a/src/plugins/vcsbase/vcsbaseeditor.cpp b/src/plugins/vcsbase/vcsbaseeditor.cpp
index 54e3823812..f7a98dec20 100644
--- a/src/plugins/vcsbase/vcsbaseeditor.cpp
+++ b/src/plugins/vcsbase/vcsbaseeditor.cpp
@@ -67,19 +67,23 @@
 /*!
     \enum VcsBase::EditorContentType
 
-    \brief Contents of a VcsBaseEditor and its interaction.
+    This enum describes the contents of a VcsBaseEditor and its interaction.
 
     \value RegularCommandOutput  No special handling.
-    \value LogOutput  Log of a file under revision control. Provide  'click on change'
-           description and 'Annotate' if is the log of a single file.
-    \value AnnotateOutput  Color contents per change number and provide 'click on change' description.
-           Context menu offers "Annotate previous version". Expected format:
+    \value LogOutput  Log of a file under revision control. Provide a
+           description of the change that users can click to view detailed
+           information about the change and \e Annotate for the log of a
+           single file.
+    \value AnnotateOutput  Color contents per change number and provide a
+           clickable change description.
+           Context menu offers annotate previous version functionality.
+           Expected format:
            \code
            <change description>: file line
            \endcode
-    \value DiffOutput  Diff output. Might includes describe output, which consists of a
-           header and diffs. Interaction is 'double click in  hunk' which
-           opens the file. Context menu offers 'Revert chunk'.
+    \value DiffOutput  Diff output. Might include describe output, which consists of a
+           header and diffs. Double-clicking the chunk opens the file. The context
+           menu offers the functionality to revert the chunk.
 
     \sa VcsBase::VcsBaseEditorWidget
 */
@@ -185,13 +189,14 @@ class AbstractTextCursorHandler : public QObject
 public:
     AbstractTextCursorHandler(VcsBaseEditorWidget *editorWidget = 0);
 
-    /*! \brief Try to find some matching contents under \p cursor
+    /*! Tries to find some matching contents under \a cursor.
      *
-     *  It's the first function to be called because it changes the internal state of the handler.
-     *  Other functions (highlightCurrentContents(), handleCurrentContents(), ...) use the result
-     *  of the matching
+     *  It is the first function to be called because it changes the internal
+     *  state of the handler. Other functions (such as
+     *  highlightCurrentContents() and handleCurrentContents()) use the result
+     *  of the matching.
      *
-     *  \return true If contents could be found
+     *  Returns \c true if contents could be found.
      */
     virtual bool findContentsUnderCursor(const QTextCursor &cursor);
 
@@ -204,8 +209,8 @@ public:
     //! Contents matched with the last call to findContentsUnderCursor()
     virtual QString currentContents() const = 0;
 
-    /*! \brief Fill \p menu with contextual actions applying to the contents matched
-     *         with findContentsUnderCursor()
+    /*! Fills \a menu with contextual actions applying to the contents matched
+     *  with findContentsUnderCursor().
      */
     virtual void fillContextMenu(QMenu *menu, EditorContentType type) const = 0;
 
@@ -378,7 +383,7 @@ QAction *ChangeTextCursorHandler::createCopyRevisionAction(const QString &change
  *  http://qt-project.org/.
  *
  *  The URL pattern can be redefined in sub-classes with setUrlPattern(), by default the pattern
- *  works for hyper-text URL
+ *  works for hyper-text URLs.
  */
 class UrlTextCursorHandler : public AbstractTextCursorHandler
 {