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>

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).

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
+    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 "Browse..." button and
+    has been entered for the current field. Optionally, a \gui Browse button and
     completer can be added.
 */
 

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)

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'
+    \value LogOutput  Log of a file under revision control. Provide a
-           description and 'Annotate' if is the log of a single file.
+           description of the change that users can click to view detailed
-    \value AnnotateOutput  Color contents per change number and provide 'click on change' description.
+           information about the change and \e Annotate for the log of a
-           Context menu offers "Annotate previous version". Expected format:
+           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
+    \value DiffOutput  Diff output. Might include describe output, which consists of a
-           header and diffs. Interaction is 'double click in  hunk' which
+           header and diffs. Double-clicking the chunk opens the file. The context
-           opens the file. Context menu offers 'Revert chunk'.
+           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.
+     *  It is the first function to be called because it changes the internal
-     *  Other functions (highlightCurrentContents(), handleCurrentContents(), ...) use the result
+     *  state of the handler. Other functions (such as
-     *  of the matching
+     *  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
+    /*! Fills \a menu with contextual actions applying to the contents matched
-     *         with findContentsUnderCursor()
+     *  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
 {