QmlJS: Improve ModelManagerInterface API, add docs.

Change-Id: Ic65d767cbad85de89dffaac66d9e80d8d467f04a
Reviewed-on: http://codereview.qt.nokia.com/3851
Reviewed-by: Leandro T. C. Melo <leandro.melo@nokia.com>

src/libs/qmljs/qmljsmodelmanagerinterface.cpp

@@ -34,6 +34,24 @@
 
 using namespace QmlJS;
 
+/*!
+    \class QmlJS::ModelManagerInterface
+    \brief Interface to the global state of the QmlJS code model.
+    \sa QmlJS::Document QmlJS::Snapshot QmlJSTools::Internal::ModelManager
+
+    The ModelManagerInterface is an interface for global state and actions in
+    the QmlJS code model. It is implemented by \l{QmlJSTools::Internal::ModelManager}
+    and the instance can be accessed through ModelManagerInterface::instance().
+
+    One of its primary concerns is to keep the Snapshots it
+    maintains up to date by parsing documents and finding QML modules.
+
+    It has a Snapshot that contains only valid Documents,
+    accessible through ModelManagerInterface::snapshot() and a Snapshot with
+    potentially more recent, but invalid documents that is exposed through
+    ModelManagerInterface::newestSnapshot().
+*/
+
 static ModelManagerInterface *g_instance = 0;
 
 ModelManagerInterface::ModelManagerInterface(QObject *parent)

src/libs/qmljs/qmljsmodelmanagerinterface.h

@@ -119,7 +119,9 @@ public:
     static ModelManagerInterface *instance();
 
     virtual WorkingCopy workingCopy() const = 0;
-    virtual QmlJS::Snapshot snapshot(bool preferValid = true) const = 0;
+
+    virtual QmlJS::Snapshot snapshot() const = 0;
+    virtual QmlJS::Snapshot newestSnapshot() const = 0;
 
     virtual void updateSourceFiles(const QStringList &files,
                                    bool emitDocumentOnDiskChanged) = 0;