QmlJS: Documentation.

Change-Id: I2a095e38b7d79a5fb39a16d8f32b48c8e28132f6
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@nokia.com>
Reviewed-by: Fawzi Mohamed <fawzi.mohamed@nokia.com>

doc/api/qtcreator-api.qdoc

@@ -57,6 +57,10 @@
     \o \l{Utils}
     \o General utility library.
 
+    \row
+    \o \l{QmlJS}
+    \o QML and JavaScript language support library.
+
     \endtable
 
     \section2 Additional libraries

doc/config/qtcreator-developer.qdocconf

@@ -8,6 +8,7 @@ headerdirs              = . \
                           ../../src/libs/cplusplus \
                           ../../src/libs/extensionsystem \
                           ../../src/libs/utils \
+                          ../../src/libs/qmljs \
                           ../../src/libs/qtcreatorcdbext \
                           ../../src/plugins/coreplugin \
                           ../../src/plugins/find \
@@ -22,6 +23,7 @@ sourcedirs              = . \
                           ../../src/libs/cplusplus \
                           ../../src/libs/extensionsystem \
                           ../../src/libs/utils \
+                          ../../src/libs/qmljs \
                           ../../src/libs/qtcreatorcdbext \
                           ../../src/plugins/coreplugin \
                           ../../src/plugins/find \

src/libs/qmljs/qmljsbind.cpp

@@ -48,16 +48,18 @@ using namespace QmlJS::AST;
 /*!
     \class QmlJS::Bind
     \brief Collected information about a single Document.
-    \sa QmlJS::Document QmlJS::Link
+    \sa QmlJS::Document QmlJS::Context
 
-    Each QmlJS::Document owns a instance of Bind. It provides access to data
+    Each QmlJS::Document owns an instance of Bind. It provides access to data
     that can be derived by looking at the document in isolation. If you need
-    information that goes beyond that, you need to create a
-    \l{QmlJS::Context} using \l{QmlJS::Link}.
+    information that goes beyond that, you need to use a
+    \l{QmlJS::Context}.
 
     The document's imports are classified and available through imports().
 
-    It allows AST to code model lookup through findQmlObject() and findFunctionScope().
+    This class makes the structural information found in the AST available
+    for analysis through \l{QmlJS::Value} instances. See findQmlObject(),
+    idEnvironment(), rootObjectValue() and findAttachedJSScope().
 */
 
 Bind::Bind(Document *doc, QList<DiagnosticMessage> *messages, bool isJsLibrary, const QList<ImportInfo> &jsImports)

src/libs/qmljs/qmljscontext.cpp

@@ -37,6 +37,20 @@
 using namespace QmlJS;
 using namespace QmlJS::AST;
 
+/*!
+    \class QmlJS::Context
+    \brief Holds information about relationships between documents in a QmlJS::Snapshot.
+    \sa QmlJS::Document QmlJS::Link QmlJS::Snapshot
+
+    Contexts are usually created through \l{QmlJS::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().
+*/
+
 ContextPtr Context::create(const QmlJS::Snapshot &snapshot, ValueOwner *valueOwner, const ImportsPerDocument &imports)
 {
     QSharedPointer<Context> result(new Context(snapshot, valueOwner, imports));

src/libs/qmljs/qmljsdocument.cpp

@@ -46,13 +46,17 @@ using namespace QmlJS::AST;
     \brief A Qml or JavaScript document.
     \sa QmlJS::Snapshot
 
-    Documents are usually created by the \l{QmlJSEditor::Internal::ModelManager}
+    Documents are usually created by the \l{QmlJS::ModelManagerInterface}
     and stored in a \l{QmlJS::Snapshot}. They allow access to data such as
     the file path, source code, abstract syntax tree and the \l{QmlJS::Bind}
     instance for the document.
 
     To make sure unused and outdated documents are removed correctly, Document
     instances are usually accessed through a shared pointer, see \l{Document::Ptr}.
+
+    Documents in a Snapshot are immutable: They, or anything reachable through them,
+    must not be changed. This allows Documents to be shared freely among threads
+    without extra synchronization.
 */
 
 /*!
@@ -60,7 +64,7 @@ using namespace QmlJS::AST;
     \brief A Qml library.
     \sa QmlJS::Snapshot
 
-    A LibraryInfo is created when the \l{QmlJSEditor::Internal::ModelManager} finds
+    A LibraryInfo is created when the \l{QmlJS::ModelManagerInterface} finds
     a Qml library and parses the qmldir file. The instance holds information about
     which Components the library provides and which plugins to load.
 
@@ -77,7 +81,7 @@ using namespace QmlJS::AST;
     A Snapshot holds and offers access to a set of Document and LibraryInfo instances.
 
     Usually Snapshots are copies of the snapshot maintained and updated by the
-    \l{QmlJSEditor::Internal::ModelManager} that updates its instance as parsing
+    \l{QmlJS::ModelManagerInterface} that updates its instance as parsing
     threads finish and new information becomes available.
 */
 

src/libs/qmljs/qmljsdocument.h

@@ -43,8 +43,6 @@
 #include "parser/qmljsengine_p.h"
 #include "qmljs_global.h"
 
-QT_QML_BEGIN_NAMESPACE
-
 namespace QmlJS {
 
 class Bind;
@@ -239,6 +237,4 @@ public:
 
 } // namespace QmlJS
 
-QT_QML_END_NAMESPACE
-
 #endif // QMLDOCUMENT_H

src/libs/qmljs/qmljslink.cpp

@@ -125,15 +125,13 @@ public:
 
 /*!
     \class QmlJS::Link
-    \brief Initializes the Context for a Document.
-    \sa QmlJS::Document QmlJS::Context
+    \brief Creates a Context for a Snapshot.
+    \sa QmlJS::Context QmlJS::Snapshot
 
-    Initializes a context by resolving imports and building the root scope
-    chain. Currently, this is a expensive operation.
+    Initializes a context by resolving imports. This is an expensive operation.
 
-    It's recommended to use a the \l{LookupContext} returned by
-    \l{QmlJSEditor::SemanticInfo::lookupContext()} instead of building a new
-    \l{Context} with \l{Link}.
+    Instead of making a fresh context, consider reusing the one maintained in the
+    \l{QmlJSEditor::SemanticInfo} of a \l{QmlJSEditor::QmlJSTextEditorWidget}.
 */
 
 Link::Link(const Snapshot &snapshot, const QStringList &importPaths, const LibraryInfo &builtins)

src/libs/qmljs/qmljsmodelmanagerinterface.h

@@ -46,8 +46,6 @@ namespace ProjectExplorer {
     class Project;
 }
 
-QT_QML_BEGIN_NAMESPACE
-
 namespace QmlJS {
 
 class Snapshot;
@@ -170,6 +168,4 @@ signals:
 
 } // namespace QmlJS
 
-QT_QML_END_NAMESPACE
-
 #endif // QMLJSMODELMANAGERINTERFACE_H

src/libs/qmljs/qmljsutils.cpp

@@ -5,6 +5,11 @@
 using namespace QmlJS;
 using namespace QmlJS::AST;
 
+/*!
+  \namespace QmlJS
+  QML and JavaScript language support library
+*/
+
 namespace {
 class SharedData
 {

src/libs/qmljs/qmljsvalueowner.cpp

@@ -34,6 +34,17 @@
 
 using namespace QmlJS;
 
+/*!
+    \class QmlJS::ValueOwner
+    \brief Manages the lifetime of \l{QmlJS::Value}s.
+    \sa QmlJS::Value
+
+    Values are usually created on a ValueOwner. When the ValueOwner is destroyed
+    it deletes all values it has registered.
+
+    A ValueOwner also provides access to various default values.
+*/
+
 namespace {
 
 ////////////////////////////////////////////////////////////////////////////////