QmlJS: Add documentation for ScopeChain.

Clear up Context documentation a little.

Change-Id: I2ede3dc0f15a972d2748cef1aa579a04f0786106
Reviewed-by: Leandro Melo <leandro.melo@nokia.com>

src/libs/qmljs/qmljscontext.cpp

@@ -42,13 +42,18 @@ using namespace QmlJS::AST;
     \brief Holds information about relationships between documents in a Snapshot.
     \sa Document Link Snapshot
 
-    Contexts are usually created through Link.
-
-    Once created, a Context is immutable and can be freely shared between threads.
+    Contexts are usually created through Link. Once created, a Context is immutable
+    and can be freely shared between threads.
 
     Their main purpose is to allow lookup of types with lookupType() and resolving
-    of references through lookupReference(). Information about the imports of
-    a QmlJS::Document can be accessed with imports().
+    of references through lookupReference(). As such, they form the basis for creating
+    a ScopeChain.
+
+    Information about the imports of a Document can be accessed with imports().
+
+    When dealing with a QmlJSEditor::QmlJSTextEditorWidget it is unnecessary to
+    construct a new Context manually. Instead use
+    QmlJSTextEditorWidget::semanticInfo()::context.
 */
 
 ContextPtr Context::create(const QmlJS::Snapshot &snapshot, ValueOwner *valueOwner, const ImportsPerDocument &imports)

src/libs/qmljs/qmljsscopechain.cpp

@@ -36,6 +36,26 @@
 
 using namespace QmlJS;
 
+/*!
+    \class QmlJS::ScopeChain
+    \brief Describes the scopes used for global lookup in a specific location.
+    \sa Document Context ScopeBuilder
+
+    A ScopeChain is used to perform global lookup with the lookup() method and
+    to access information about the enclosing scopes.
+
+    Once constructed for a Document in a Context it represents the root scope of
+    that Document. From there, a ScopeBuilder can be used to push and pop scopes
+    corresponding to functions, object definitions, etc.
+
+    It is an error to use the same ScopeChain from multiple threads; use a copy.
+    Copying is cheap. Initial construction is currently expensive.
+
+    When a QmlJSEditor::QmlJSTextEditorWidget is available, there's no need to
+    construct a new ScopeChain. Instead use
+    QmlJSTextEditorWidget::semanticInfo()::scopeChain().
+*/
+
 QmlComponentChain::QmlComponentChain(const Document::Ptr &document)
     : m_document(document)
 {