Documentation: Snippets support

Change-Id: I40dd20a7da93ab7af3044d9bebf49e15dbfb7aa4
Reviewed-on: http://codereview.qt.nokia.com/184
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@nokia.com>

src/plugins/texteditor/snippets/isnippetprovider.cpp

@@ -34,8 +34,73 @@
 
 using namespace TextEditor;
 
+/*!
+    \group Snippets
+    \title Snippets for Editors
+
+    Snippets typically consist of chunks of code in a programming language (although they
+    can also be plain text) which you would like to avoid re-typing every time. They
+    are triggered in the same way as the completions (see \l{CodeAssist}{Providing
+    Code Assist}).
+
+    In order to create a new group of snippets two steps are necessary:
+    \list
+        \o Implement the TextEditor::ISnippetProvider interface and register it in
+        the extension system.
+        \o Create an XML configuration file and place it in the
+        /share/qtcreator/snippets directory. As an example of the file format
+        please take a look at the already available ones. The meaning and consistency rules
+        of the fields are described below:
+        \list
+            \o group - This is the group in which the snippet belongs in the user interface.
+            It must match TextEditor::ISnippetProvider::groupId().
+            \o id - A unique string that identifies this snippet among all others available.
+            The recommended practice is to prefix it with the group so it is easier to have
+            such control on a file level.
+            \o trigger - The sequence of characters to be compared by the completion engine
+            in order to display this snippet as a code assist proposal.
+            \o complement - Additional information that is displayed in the code assist
+            proposal so it is possible to disambiguate similar snippets that have the
+            same trigger.
+        \endlist
+    \endlist
+
+    All XML configuration files found in the directory mentioned above are parsed by
+    Qt Creator. However, only the ones which are associated with known groups (specified
+    by a provider) are taken into consideration.
+*/
+
+/*!
+    \class TextEditor::ISnippetProvider
+    \brief The ISnippetProvider class acts as an interface for providing groups of snippets.
+    \ingroup Snippets
+
+    Known implementors of this interface are the CppSnippetProvider, the QmlJSSnippetProvider,
+    and the PlainTextSnippetProvider.
+*/
+
 ISnippetProvider::ISnippetProvider() : QObject()
 {}
 
 ISnippetProvider::~ISnippetProvider()
 {}
+
+/*!
+    \fn QString TextEditor::ISnippetProvider::groupId() const
+
+    Returns the unique group id to which this provider is associated.
+*/
+
+/*!
+    \fn QString TextEditor::ISnippetProvider::displayName() const
+
+    Returns the name to be displayed in the user interface for snippets that belong to the group
+    associated with this provider.
+*/
+
+/*!
+    \fn void TextEditor::ISnippetProvider::decorateEditor(SnippetEditorWidget *editor) const
+
+    This is a hook which allows you to apply customizations such as highlighting or indentation
+    to the snippet editor.
+*/

src/plugins/texteditor/snippets/snippeteditor.cpp

@@ -41,6 +41,13 @@
 
 using namespace TextEditor;
 
+/*!
+    \class TextEditor::SnippetEditorWidget
+    \brief The SnippetEditorWidget class is a lightweight editor for code snippets
+    with basic support for syntax highlighting, indentation, and others.
+    \ingroup Snippets
+*/
+
 SnippetEditor::SnippetEditor(SnippetEditorWidget *editor)
     : BaseTextEditor(editor)
 {