docs: Review the Document and Project API

Update the documentation a bit.

Related to KDAB#54

docs/API/script/document.md

@@ -34,6 +34,8 @@ A document is a file loaded by Knut and that can be used in script (either to ge
 
 #### <a name="errorString"></a>string **errorString**
 
+Returns the error string if an error occurred while loading the document, otherwise returns an empty string.
+
 #### <a name="exists"></a>bool **exists**
 
 Returns true if the document is a file on the disk, otherwise returns false.

docs/API/script/project.md

@@ -24,7 +24,7 @@ import Script
 ||**[closeAll](#closeAll)**()|
 |[Document](../script/document.md) |**[get](#get)**(string fileName)|
 |[Document](../script/document.md) |**[open](#open)**(string fileName)|
-||**[openPrevious](#openPrevious)**(int index)|
+||**[openPrevious](#openPrevious)**(int index = 1)|
 ||**[saveAllDocuments](#saveAllDocuments)**()|
 
 ## Detailed Description
@@ -77,18 +77,23 @@ Close all documents. If the document has some changes, save the changes.
 
 #### <a name="get"></a>[Document](../script/document.md) **get**(string fileName)
 
-Get the document for the given `fileName`. If the document is not opened yet, open it. If the document already
-exists, returns the same instance, a document can't be open twice. If the fileName is relative, use the root path as
-the base.
+Gets the document for the given `fileName`. If the document is not opened yet, open it. If the document
+is already opened, returns the same instance, a document can't be open twice. If the fileName is relative, use the
+root path as the base.
 
-*Note:* this command does not change the current document.
+If the document does not exist, creates a new document (but don't save it yet).
+
+!!! note
+    This command does not change the current document.
 
 #### <a name="open"></a>[Document](../script/document.md) **open**(string fileName)
 
-Opens a document for the given `fileName` and make it current. If the document already exists, returns the same
-instance, a document can't be open twice. If the fileName is relative, use the root path as the base.
+Opens or creates a document for the given `fileName` and make it current. If the document is already opened, returns
+the same instance, a document can't be open twice. If the fileName is relative, use the root path as the base.
+
+ If the document does not exist, creates a new document (but don't save it yet).
 
-#### <a name="openPrevious"></a>**openPrevious**(int index)
+#### <a name="openPrevious"></a>**openPrevious**(int index = 1)
 
 Open a previously opened document. `index` is the position of this document in the last opened document.
 

src/core/document.cpp

@@ -54,6 +54,7 @@ namespace Core {
  */
 /*!
  * \qmlproperty string Document::errorString
+ * Returns the error string if an error occurred while loading the document, otherwise returns an empty string.
  */
 /*!
  * \qmlproperty bool Document::hasChanged

src/core/project.cpp

@@ -297,11 +297,14 @@ Document *Project::getDocument(QString fileName, bool moveToBack)
 
 /*!
  * \qmlmethod Document Project::get(string fileName)
- * Get the document for the given `fileName`. If the document is not opened yet, open it. If the document already
- * exists, returns the same instance, a document can't be open twice. If the fileName is relative, use the root path as
- * the base.
+ * Gets the document for the given `fileName`. If the document is not opened yet, open it. If the document
+ * is already opened, returns the same instance, a document can't be open twice. If the fileName is relative, use the
+ * root path as the base.
  *
- * *Note:* this command does not change the current document.
+ * If the document does not exist, creates a new document (but don't save it yet).
+ *
+ * !!! note
+ *     This command does not change the current document.
  */
 Document *Project::get(const QString &fileName)
 {
@@ -312,8 +315,10 @@ Document *Project::get(const QString &fileName)
 
 /*!
  * \qmlmethod Document Project::open(string fileName)
- * Opens a document for the given `fileName` and make it current. If the document already exists, returns the same
- * instance, a document can't be open twice. If the fileName is relative, use the root path as the base.
+ * Opens or creates a document for the given `fileName` and make it current. If the document is already opened, returns
+ * the same instance, a document can't be open twice. If the fileName is relative, use the root path as the base.
+ *
+ *  If the document does not exist, creates a new document (but don't save it yet).
  */
 Document *Project::open(const QString &fileName)
 {
@@ -360,7 +365,7 @@ void Project::saveAllDocuments()
 }
 
 /*!
- * \qmlmethod Project::openPrevious(int index)
+ * \qmlmethod Project::openPrevious(int index = 1)
  * Open a previously opened document. `index` is the position of this document in the last opened document.
  *
  * `document.openPrevious(1)` (the default) opens the last document, like Ctrl+Tab in any editors.