Documentation: Snippets support

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

doc/api/external-tool-spec.qdoc

@@ -21,7 +21,6 @@
 
 /*!
     \contentspage{index.html}{Qt Creator}
-    \previouspage qtcreator-code-snippet-config.html
     \page external-tool-spec.html
     \nextpage coding-style.html
 

doc/api/qtcreator-api.qdoc

@@ -115,8 +115,8 @@
     \o \l{TextEditor}
     \o This is where everything starts if you want to create a text editor. Besides
     the base editor itself, this plugin contains APIs for supporting functionality
-    like snippets, highlighting, \l{CodeAssist}{code assist}, indentation and style,
+    like \l{Snippets}{snippets}, highlighting, \l{CodeAssist}{code assist}, indentation
-    and others.
+    and style, and others.
 
     \endtable
 */

doc/api/qtcreator-code-snippet-config.qdoc

@@ -1,41 +0,0 @@
-/****************************************************************************
-**
-** This file is part of Qt Creator
-**
-** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
-**
-** Contact: Nokia Corporation (info@qt.nokia.com)
-**
-**
-** GNU Free Documentation License
-**
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of this
-** file.
-**
-** If you have questions regarding the use of this file, please contact
-** Nokia at qt-info@nokia.com.
-**
-****************************************************************************/
-
-/*!
-    \previouspage
-    \page qtcreator-code-snippet-config.html
-    \title Code Snippet Configuration Files
-    \nextpage
-
-    You can use code snippet configuration files to <add the purpose of the
-    files>.
-
-    Name the configuration files as follows:
-
-    Copy the configuration files to the following directory:
-
-
-
-    \section1 File Syntax
-
-
-
-*/

doc/api/qtcreator-dev.qdoc

@@ -45,19 +45,21 @@
     whole files or classes spread over multiple files, or complete projects,
     you can create code snippets, templates, and wizards for that purpose.
 
-    \section2 Code Snippets
+    \section2 Snippets
 
-    Typically, code snippets consist of a few lines of code that you regularly
+    Typically, snippets consist of a few lines of code (although they
+    can also be plain text) that you regularly
     want to insert into a bigger body of code, but do not want to type each
     time. For example, \c while and \c for loops, \c if-else and \c try-catch
     constructs, and class skeletons. Snippets are triggered in the same way as
-    normal code completion. Qt Creator contains a set of preconfigured snippets
+    normal code completion (see \l{Code Assist}{Providing Code Assist}).
+    Qt Creator contains a set of preconfigured snippets groups
     to which you can add your own snippets.
 
     \list
     \o \l{http://doc.qt.nokia.com/qtcreator/creator-completing-code.html#editing-code-snippets}
-         {Adding Code Snippets in Qt Creator}
+         {Snippets User Interface}
-    \o \l{Code Snippet Configuration Files}
+    \o \l{Snippets} {Adding Snippets Groups}
     \endlist
 
     \section2 File, Class and Project Templates
@@ -239,7 +241,6 @@
             \endlist
         \o  Reference
             \list
-                \o  \l{Code Snippet Configuration Files}
                 \o  \l{http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html}
                     {MIME Type Specification Files}
                 \o  \l{External Tool Specification Files}

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