revised SourcetrailDBWriter API documentation and related classes

CHANGELOG.md

@@ -2,6 +2,6 @@
 
 ## v1.db23.p0
 
-**2018-12-18**
+**2018-12-19**
 
 * First official release of the SourcetrailDB project.

core/CMakeLists.txt

@@ -33,7 +33,6 @@ set(LIB_HDR_FILES
 	include/DefinitionKind.h
 	include/EdgeKind.h
 	include/LocationKind.h
-	include/NameElement.h
 	include/NameHierarchy.h
 	include/NodeKind.h
 	include/ReferenceKind.h

core/include/DatabaseStorage.h

@@ -45,7 +45,7 @@ namespace sourcetrail
 	{
 	public:
 		static int getSupportedDatabaseVersion();
-		static std::shared_ptr<DatabaseStorage> openDatabase(const std::string& dbFilePath);
+		static std::unique_ptr<DatabaseStorage> openDatabase(const std::string& dbFilePath);
 		~DatabaseStorage();
 
 		void setupDatabase();

core/include/NameElement.h

@@ -1,35 +0,0 @@
-/*
-* Copyright 2018 Coati Software KG
-*
-* Licensed under the Apache License, Version 2.0 (the "License");
-* you may not use this file except in compliance with the License.
-* You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
-
-#ifndef SOURCETRAIL_NAME_ELEMENT_H
-#define SOURCETRAIL_NAME_ELEMENT_H
-
-#include <string>
-
-namespace sourcetrail
-{
-	/**
-	* Struct that represents a single hierarchical element that is part of a symbol's name.
-	*/
-	struct NameElement
-	{
-		std::string prefix;
-		std::string name;
-		std::string postfix;
-	};
-}
-
-#endif // SOURCETRAIL_NAME_ELEMENT_H

core/include/NameHierarchy.h

@@ -20,15 +20,27 @@
 #include <string>
 #include <vector>
 
-#include "NameElement.h"
-
 namespace sourcetrail
 {
+	/**
+	* Struct that represents a single hierarchical element that is part of a symbol's name.
+	*
+	*  prefix: optional prefix used for unique identification and shown in tooltips
+	*  name: name represented by this element
+	*  postfix: optional prefix used for unique identification and shown in tooltips
+	*/
+	struct NameElement
+	{
+		std::string prefix;
+		std::string name;
+		std::string postfix;
+	};
+
 	/**
 	* Struct that represents an entire name of a symbol.
 	*
-	* TODO: explain prefix and postfix
+	*  nameDelimiter: delimiter added between name elements
-	* TODO: alway provide prefix and postfix of all name elements to make them unique. Example from C++ (2 foo::bar (foo has different signature)
+	*  nameElements: all name elements that make up the hierarchy
 	*/
 	struct NameHierarchy
 	{
@@ -36,9 +48,51 @@ namespace sourcetrail
 		std::vector<NameElement> nameElements;
 	};
 
-	std::string serializeNameHierarchyToDatabaseString(const NameHierarchy& nameHierarchy);
+	/**
+	 * Converts a NameHierarchy to a JSON string
+	 *
+	 *  param: nameHierarchy - the name hierarchy to convert to JSON string
+	 *
+	 *  return: a JSON object of the form:
+	 *    {
+	 *      "name_delimiter" : "."
+	 *      "name_elements" : [
+	 *        {
+	 *          "prefix" : "",
+	 *          "name" : "",
+	 *          "postfix" : ""
+	 *        },
+	 *        ...
+	 *      ]
+	 *    }
+	 */
 	std::string serializeNameHierarchyToJson(const NameHierarchy& nameHierarchy);
+
+	/**
+	 * Converts a JSON string to a NameHierarchy
+	 *
+	 *  param: serializedNameHierarchy - JSON object string of the form:
+	 *    {
+	 *      "name_delimiter" : "."
+	 *      "name_elements" : [
+	 *        {
+	 *          "prefix" : "",
+	 *          "name" : "",
+	 *          "postfix" : ""
+	 *        },
+	 *        ...
+	 *      ]
+	 *    }
+	 *  param: error - optional pointer to a string, where an error message will be set
+	 *
+	 *  return: NameHierarchy object. Empty on failure.
+	 */
 	NameHierarchy deserializeNameHierarchyFromJson(const std::string& serializedNameHierarchy, std::string* error = nullptr);
+
+	/**
+	 * INTERNAL: Converts a NameHierarchy to a string in Sourcetrail database format
+	 */
+	std::string serializeNameHierarchyToDatabaseString(const NameHierarchy& nameHierarchy);
 }
 
 #endif // SOURCETRAIL_NAME_HIERARCHY_H

core/include/SourceRange.h

@@ -22,8 +22,8 @@ namespace sourcetrail
 	/**
 	* Struct that represents the location of a range of characters in a source file.
 	*
-	* Note: Line and column numbers start at 1 instead of 0!
+	*  note: Line and column numbers start at 1 instead of 0!
-	* Note: The SourceRange includes both, the start and the end column number.
+	*  note: The SourceRange includes both, the start and the end column number.
 	*/
 	struct SourceRange
 	{

core/include/SourcetrailDBWriter.h

@@ -30,44 +30,48 @@
 
 namespace sourcetrail
 {
-	class DatabaseStorage;	// forward declaration prevents leakage of sqlite include dependency to users
+	class DatabaseStorage;
-							// of the SourcetrailDBWriter
 
 	/**
-	 * Class wrapping the main interface for writing data to a Sourcetrail project database.
+	 * SourcetrailDBWriter
 	 *
-	 * This class can be used to manage a Sourcetrail database file and to write information to such
+	 * This class is the main interface for writing data to a Sourcetrail project database.
-	 * a file.
+	 * It be used to manage a Sourcetrail database file and to write information to it.
 	 *
 	 * The following code snippet illustrates a very basic usage of the SourcetrailDBWriter class:
 	 *
-	 * sourcetrail::SourcetrailDBWriter writer;
+	 *   sourcetrail::SourcetrailDBWriter writer;
-	 * writer.open("MyProject.srctrldb");
+	 *   writer.open("MyProject.srctrldb");
-	 * writer.recordSymbol({ "::",{ { "void", "foo", "()" } } });
+	 *   writer.recordSymbol({ "::",{ { "void", "foo", "()" } } });
-	 * writer.close();
+	 *   writer.close();
 	 */
 	class SourcetrailDBWriter
 	{
 	public:
 		SourcetrailDBWriter();
+		~SourcetrailDBWriter();
 
 		/**
-		 * Provides the version of the SourcetrailDB Core as string with format "vXX_dbYY_pZZ"
+		 * Provides the version of the SourcetrailDB Core as string with format "vXX.dbYY.pZZ"
 		 *
-		 *  - "XX" marks the interface version of the API. This version is increases on every change
+		 *  - XX: interface version. This version increases on every change that breaks backwards
-		 *    that breaks backwards compatibility of the API.
+		 *        compatibility.
-		 *  - "YY" marks the version of the database that will be generated when using the
+		 *  - YY: Sourcetrail database version. This version needs to match the database version
-		 *    SourcetrailDB API. This version needs to match the database version of the Sourcetrail
+		 *        of the used Sourcetrail instance. You can find the database version of Sourcetrail
-		 *    instance that is used to open the generated database file to be compatible.
+		 *        in its About dialog.
-		 *  - "ZZ" marks the patch number of the build. It will increase with every release that
+		 *  - ZZ: patch number of the build. It will increase with every release that publishes
-		 *    publishes bugfixes and features that don't break any compatibility.
+		 *        bugfixes and features that don't break any compatibility.
+		 *
+		 *  return: version string
 		 */
 		std::string getVersionString() const;
 
 		/**
 		 * Provides the supported database version as integer
 		 *
-		 * See getVersionString() for details
+		 *  return: supported database version
+		 *
+		 *  see: getVersionString() for details
 		 */
 		int getSupportedDatabaseVersion() const;
 
@@ -77,21 +81,25 @@ namespace sourcetrail
 		 * The last error is empty if no error occurred since instantiation of the class or since the
 		 * error has last been cleared.
 		 *
-		 * See: clearLastError()
+		 *  return: error message of last error that occured
+		 *
+		 *  see: clearLastError()
 		 */
 		const std::string& getLastError() const;
 
 		/**
 		 * Modifies the stored error message
 		 *
-		 * See: getLastError()
+		 *  param: error - the new error message
+		 *
+		 *  see: getLastError()
 		 */
 		void setLastError(const std::string& error) const;
 
 		/**
 		 * Clears the stored error message
 		 *
-		 * See: getLastError()
+		 *  see: getLastError()
 		 */
 		void clearLastError();
 
@@ -101,53 +109,54 @@ namespace sourcetrail
 		 * Call this method to open a Sourcetrail database file. If the database does not have any
 		 * related .srctrlprj project file, a minimal project file will be created that allows for
 		 * opening the database with Sourcetrail.
-		 * Param databaseFilePath - absolute file path of the database file, including file extension
+		 *
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *  param: databaseFilePath - absolute file path of the database file, including file extension
-		 * can be checked for more detailed information.
+		 *
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
 		 */
 		bool open(const std::string& databaseFilePath);
 
 		/**
 		 * Closes the currently open Sourcetrail database
 		 *
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *  return: Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
+		 *    can be checked for more detailed information.
 		 *
-		 * See open(const std::string& databaseFilePath)
+		 *  see: open(const std::string& databaseFilePath)
 		 */
 		bool close();
 
 		/**
 		 * Clears the currently open Sourcetrail database
 		 *
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
-		 * can be checked for more detailed information.
 		 *
-		 * See open(const std::string& databaseFilePath)
+		 *  see: open(const std::string& databaseFilePath)
 		 */
 		bool clear();
 
 		/**
 		 * Checks if the currently open database file contains any data
 		 *
-		 * Returns true after opening a non-existing database file or clearing the open Sourcetrail
+		 *  return: true after opening a non-existing database file or clearing the open database
-		 * database.
 		 */
 		bool isEmpty() const;
 
 		/**
 		 * Checks if the currently open database is compatible with the SourcetrailDBWriter version.
 		 *
-		 * Returns true for an empty database or a database that has been created with the same
+		 *  return: true for an empty database or a database that has been created with the same
-		 * database version.
+		 *   database version.
 		 *
-		 * See: getSupportedDatabaseVersion()
+		 *  see: getSupportedDatabaseVersion()
-		 * See: getLoadedDatabaseVersion()
+		 *  see: getLoadedDatabaseVersion()
 		 */
 		bool isCompatible() const;
 
 		/**
 		 * Provides the database version of the loaded database file as an integer
+		 *
+		 *  return: database version of loaded database
 		 */
 		int getLoadedDatabaseVersion() const;
 
@@ -158,47 +167,46 @@ namespace sourcetrail
 		 * been called, wrapping multiple calls that record data with one transaction significantly
 		 * increases the performance of these database operations.
 		 *
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
-		 * can be checked for more detailed information.
 		 *
-		 * See: commitTransaction()
+		 *  see: commitTransaction()
-		 * See: rollbackTransaction()
+		 *  see: rollbackTransaction()
 		 */
 		bool beginTransaction();
 
 		/**
 		 * Ends the current transaction and writes all of its changes persistently to the database
 		 *
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
-		 * can be checked for more detailed information.
 		 */
 		bool commitTransaction();
 
 		/**
 		 * Reverts the database to the state it was in before the current transaction was started
 		 *
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
-		 * can be checked for more detailed information.
 		 */
 		bool rollbackTransaction();
 
 		/**
 		 * Reduces the on disk memory consumption of the open database to a minimum
 		 *
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
-		 * can be checked for more detailed information.
 		 */
 		bool optimizeDatabaseMemory();
 
 		/**
 		 * Stores a symbol to the database
 		 *
-		 * Param nameHierarchy - the name of the symbol to store.
+		 *  note: Calling this method multiple times with the same input on the same Sourcetrail
-		 * Returns an integer id of the stored symbol. Calling this method multiple times with the same
+		 *    database will always return the same id.
-		 * input on the same Sourcetrail database will always return the same id. If this operation fails
-		 * the invalid id 0 is returned and getLastError() can be checked for more detailed information.
 		 *
-		 * See: NameHierarchy
+		 *  param: nameHierarchy - the name of the symbol to store.
+		 *
+		 *  return: symbolId - integer id of the stored symbol. 0 on failure. getLastError()
+		 *    provides the error message.
+		 *
+		 *  see: NameHierarchy
 		 */
 		int recordSymbol(const NameHierarchy& nameHierarchy);
 
@@ -212,12 +220,12 @@ namespace sourcetrail
 		 * This may be desired while recording a reference to a symbol with a definition that is located
 		 * outside of the indexed source files.
 		 *
-		 * Param symbolId - the id of the symbol for which a DefinitionKind shall be recorded.
+		 *  param: symbolId - the id of the symbol for which a DefinitionKind shall be recorded.
-		 * Param definitionKind - the DefinitionKind that shall be recorded for the respective symbol.
+		 *  param: definitionKind - the DefinitionKind that shall be recorded for the respective symbol.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
 		 *
-		 * See: DefinitionKind
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: DefinitionKind
 		 */
 		bool recordSymbolDefinitionKind(int symbolId, DefinitionKind definitionKind);
 
@@ -229,12 +237,12 @@ namespace sourcetrail
 		 * times overwrites the symbol's previously recorded SymbolKind. If no SymbolKind is recorded
 		 * for a symbol, Sourcetrail displays the type of this symbol as "symbol".
 		 *
-		 * Param symbolId - the id of the symbol for which a SymbolKind shall be recorded.
+		 *  param: symbolId - the id of the symbol for which a SymbolKind shall be recorded.
-		 * Param symbolKind - the SymbolKind that shall be recorded for the respective symbol.
+		 *  param: symbolKind - the SymbolKind that shall be recorded for the respective symbol.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
 		 *
-		 * See: SymbolKind
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: SymbolKind
 		 */
 		bool recordSymbolKind(int symbolId, SymbolKind symbolKind);
 
@@ -247,12 +255,12 @@ namespace sourcetrail
 		 * Sourcetrail will activate the symbol with the specified id. When the symbol with the specified
 		 * id is activated, this location will be displayed and highlighted by Sourcetrail.
 		 *
-		 * Param symbolId - the id of the symbol for which a location shall be recorded.
+		 *  param: symbolId - the id of the symbol for which a location shall be recorded.
-		 * Param location - the SourceRange that shall be recorded as location for the respective symbol.
+		 *  param: location - the SourceRange that shall be recorded as location for the respective symbol.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
 		 *
-		 * See: SourceRange
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: SourceRange
 		 */
 		bool recordSymbolLocation(int symbolId, const SourceRange& location);
 
@@ -262,16 +270,16 @@ namespace sourcetrail
 		 * This method allows to store a scope location for a symbol referenced by id to the database.
 		 * Calling this method with the same symbolId multiple times adds multiple scope locations for the
 		 * respective symbol. The stored location will only be displayable and not clickable. When the
-		 * symbol with the specified id is activated, this location will be displayed but not highlighted
+		 * symbol with the specified id is activated, this location will be fully displayed but not
-		 * by Sourcetrail.
+		 * highlighted by Sourcetrail.
 		 *
-		 * Param symbolId - the id of the symbol for which a scope location shall be recorded.
+		 *  param: symbolId - the id of the symbol for which a scope location shall be recorded.
-		 * Param location - the SourceRange that shall be recorded as scope location for the respective
+		 *  param: location - the SourceRange that shall be recorded as scope location for the respective
-		 * symbol.
+		 *    symbol.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
 		 *
-		 * See: SourceRange
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: SourceRange
 		 */
 		bool recordSymbolScopeLocation(int symbolId, const SourceRange& location);
 
@@ -279,22 +287,22 @@ namespace sourcetrail
 		 * Stores a signature location for a specific symbol to the database
 		 *
 		 * This method allows to store a signature location for a symbol referenced by id to the
-		 * database. Calling this method with the same symbolId multiple times adds multiple signature
+		 * database. If a signature location is recorded for a symbol, Sourcetrail will display the
-		 * locations for the respective symbol. Sourcetrail will only make use of one of the recorded
+		 * respective source code in a tooltip whenever the symbol with the referenced id or any of
-		 * signature locations, so please try to call this method only once.
+		 * that symbol's locations gets hovered.
-		 * If a signature location is recorded for a symbol, Sourcetrail will display the respective
+		 * If no signature location is recorded for a symbol, Sourcetrail will show its name hierarchy.
-		 * source code in a tooltip whenever the symbol with the referenced id or any of that symbol's
-		 * locations gets hovered.
-		 * If no signature location is recorded for a symbol, Sourcetrail will try to derive the text
-		 * of the shown tooltip from the recorded name hierarchy.
 		 *
-		 * Param symbolId - the id of the symbol for which a signature location shall be recorded.
+		 *  note: Calling this method with the same symbolId multiple times adds multiple signature
-		 * Param location - the SourceRange that shall be recorded as signature location for the
+		 *    locations for the respective symbol. It is not guaranteed which one will be used, so it is
-		 * respective symbol.
+		 *    advised to call it only once per symbol.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
 		 *
-		 * See: SourceRange
+		 *  param: symbolId - the id of the symbol for which a signature location shall be recorded.
+		 *  param: location - the SourceRange that shall be recorded as signature location for the
+		 *    respective symbol.
+		 *
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: SourceRange
 		 */
 		bool recordSymbolSignatureLocation(int symbolId, const SourceRange& location);
 
@@ -304,17 +312,20 @@ namespace sourcetrail
 		 * This method allows to store the information of symbols referencing one another to the database.
 		 * For each recorded reference Sourcetrail's graph view will display an edge that originates at
 		 * the reference's recorded context symbol and points to the recorded referenced symbol. The
-		 * recorded ReferenceKind is used to determine the color of the displayed edge and to generate a
+		 * recorded ReferenceKind is used to determine the type of the displayed edge and to generate a
 		 * description in the hover tooltip of the edge.
 		 *
-		 * Param contextSymbolId - the id of the source of the recorded reference edge
+		 *  note: Calling this method multiple times with the same input on the same Sourcetrail database
-		 * Param referencedSymbolId - the id of the target of the recorded reference edge
+		 *    will always return the same id.
-		 * Param referenceKind - kind of the recorded reference edge
-		 * Returns an integer id of the stored reference. Calling this method multiple times with the same
-		 * input on the same Sourcetrail database will always return the same id. If this operation fails
-		 * the invalid id 0 is returned and getLastError() can be checked for more detailed information.
 		 *
-		 * See: ReferenceKind
+		 *  param: contextSymbolId - the id of the source of the recorded reference edge
+		 *  param: referencedSymbolId - the id of the target of the recorded reference edge
+		 *  param: referenceKind - kind of the recorded reference edge
+		 *
+		 *  return: referenceId - integer id of the stored reference. 0 on failure. getLastError()
+		 *    provides the error message.
+		 *
+		 *  see: ReferenceKind
 		 */
 		int recordReference(int contextSymbolId, int referencedSymbolId, ReferenceKind referenceKind);
 
@@ -328,22 +339,26 @@ namespace sourcetrail
 		 * When the reference with the specified id is activated, this location will be displayed and
 		 * highlighted by Sourcetrail.
 		 *
-		 * Param referenceId - the id of the reference for which a location shall be recorded.
+		 *  param: referenceId - the id of the reference for which a location shall be recorded.
-		 * Param location - the SourceRange that shall be recorded as location for the respective reference.
+		 *  param: location - the SourceRange that shall be recorded as location for the respective
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *    reference.
-		 * can be checked for more detailed information.
 		 *
-		 * See: SourceRange
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: SourceRange
 		 */
 		bool recordReferenceLocation(int referenceId, const SourceRange& location);
 
 		/**
 		 * Stores a file to the database
 		 *
-		 * Param filePath - the absolute path to the file to store.
+		 *  note: Calling this method multiple times with the same input on the same Sourcetrail database
-		 * Returns an integer id of the stored file. Calling this method multiple times with the same
+		 *    will always return the same id.
-		 * input on the same Sourcetrail database will always return the same id. If this operation fails
+		 *
-		 * the invalid id 0 is returned and getLastError() can be checked for more detailed information.
+		 *  param: filePath - the absolute path to the file to store.
+		 *
+		 *  return: fileId - integer id of the stored file. 0 on failure. getLastError() provides the
+		 *    error message.
 		 */
 		int recordFile(const std::string& filePath);
 
@@ -354,22 +369,25 @@ namespace sourcetrail
 		 * is passed and stored as string (e.g. "cpp", "java", etc.) and allows Sourcetrail to pick the
 		 * correct syntax highlighting rules when displaying the respective source file.
 		 *
-		 * Param fileId - the id of the file for which language information shall be recorded.
+		 *  param: fileId - the id of the file for which language information shall be recorded.
-		 * Param languageIdentifier - a string that denotes the programming language the respective file
+		 *  param: languageIdentifier - a string that denotes the programming language the respective file
-		 * is written in.
+		 *    is written in.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
+		 *
-		 * can be checked for more detailed information.
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
 		 */
 		bool recordFileLanguage(int fileId, const std::string& languageIdentifier);
 
 		/**
 		 * Stores a local symbol to the database
 		 *
-		 * Param name - a name that is unique for this local symbol (e.g. the string encoded location
+		 *  note: Calling this method multiple times with the same input on the same Sourcetrail database
-		 * of the local symbol's definition).
+		 *    will always return the same id.
-		 * Returns an integer id of the stored local symbol. Calling this method multiple times with the same
+		 *
-		 * input on the same Sourcetrail database will always return the same id. If this operation fails
+		 *  param: name - a name that is unique for this local symbol (e.g. the string encoded location
-		 * the invalid id 0 is returned and getLastError() can be checked for more detailed information.
+		 *    of the local symbol's definition).
+		 *
+		 *  return: localSymbolId - integer id of the stored local symbol. 0 on failure. getLastError()
+		 *    provides the error message.
 		 */
 		int recordLocalSymbol(const std::string& name);
 
@@ -382,13 +400,13 @@ namespace sourcetrail
 		 * Sourcetrail will activate this and all other local symbol locations that share the same local
 		 * symbol id.
 		 *
-		 * Param localSymbolId - the id of the local symbol for which a location shall be recorded.
+		 *  param: localSymbolId - the id of the local symbol for which a location shall be recorded.
-		 * Param location - the SourceRange that shall be recorded as location for the respective
+		 *  param: location - the SourceRange that shall be recorded as location for the respective
-		 * local symbol.
+		 *    local symbol.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
 		 *
-		 * See: SourceRange
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: SourceRange
 		 */
 		bool recordLocalSymbolLocation(int localSymbolId, const SourceRange& location);
 
@@ -398,11 +416,11 @@ namespace sourcetrail
 		 * This method allows to store a comment location to the database. These comment locations will
 		 * be used by Sourcetrail to prevent the code view from displaying comments imcomplete.
 		 *
-		 * param location - the SourceRange of the comment to record.
+		 *  param: location - the SourceRange of the comment to record.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
 		 *
-		 * See: SourceRange
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: SourceRange
 		 */
 		bool recordCommentLocation(const SourceRange& location);
 
@@ -413,13 +431,13 @@ namespace sourcetrail
 		 * Sourcetrail's error view. When clicking the error in Sourcetrail's error list, the code view
 		 * will display this location.
 		 *
-		 * param message - an error message that will be displayed in Sourcetrail's error list.
+		 *  param: message - an error message that will be displayed in Sourcetrail's error list.
-		 * param fatal - boolean that tells Sourcetrail if this is a fatal error.
+		 *  param: fatal - boolean fatal indicates whether parsing/indexing was aborted at this point.
-		 * param location - the SourceRange of the error encountered.
+		 *  param: location - the SourceRange of the error encountered.
-		 * Returns true if the operation was successful. Otherwise false is returned and getLastError()
-		 * can be checked for more detailed information.
 		 *
-		 * See: SourceRange
+		 *  return: true if successful. false on failure. getLastError() provides the error message.
+		 *
+		 *  see: SourceRange
 		 */
 		bool recordError(const std::string& message, bool fatal, const SourceRange& location);
 
@@ -437,7 +455,7 @@ namespace sourcetrail
 
 		std::string m_projectFilePath;
 		std::string m_databaseFilePath;
-		std::shared_ptr<DatabaseStorage> m_storage;
+		std::unique_ptr<DatabaseStorage> m_storage;
 		mutable std::string m_lastError;
 	};
 }

core/src/DatabaseStorage.cpp

@@ -35,14 +35,14 @@ namespace sourcetrail
 		return DATABASE_VERSION;
 	}
 
-	std::shared_ptr<DatabaseStorage> DatabaseStorage::openDatabase(const std::string& dbFilePath)
+	std::unique_ptr<DatabaseStorage> DatabaseStorage::openDatabase(const std::string& dbFilePath)
 	{
 		try
 		{
-			std::shared_ptr<DatabaseStorage> storage = std::shared_ptr<DatabaseStorage>(new DatabaseStorage());
+			std::unique_ptr<DatabaseStorage> storage = std::unique_ptr<DatabaseStorage>(new DatabaseStorage());
 			storage->m_database.open(dbFilePath.c_str());
 			storage->executeStatement("PRAGMA foreign_keys=ON;");
-			return storage;
+			return std::move(storage);
 		}
 		catch (CppSQLite3Exception e)
 		{

core/src/NameHierarchy.cpp

@@ -20,26 +20,6 @@
 
 namespace sourcetrail
 {
-	std::string serializeNameHierarchyToDatabaseString(const NameHierarchy& nameHierarchy)
-	{
-		static std::string META_DELIMITER = "\tm";
-		static std::string NAME_DELIMITER = "\tn";
-		static std::string PARTS_DELIMITER = "\ts";
-		static std::string SIGNATURE_DELIMITER = "\tp";
-
-		std::string serialized = nameHierarchy.nameDelimiter + META_DELIMITER;
-		for (size_t i = 0; i < nameHierarchy.nameElements.size(); i++)
-		{
-			if (i != 0)
-			{
-				serialized += NAME_DELIMITER;
-			}
-			const NameElement& nameElement = nameHierarchy.nameElements[i];
-			serialized += nameElement.name + PARTS_DELIMITER + nameElement.prefix + SIGNATURE_DELIMITER + nameElement.postfix;
-		}
-		return serialized;
-	}
-
 	std::string serializeNameHierarchyToJson(const NameHierarchy& nameHierarchy)
 	{
 		typedef nlohmann::json json;
@@ -127,4 +107,24 @@ namespace sourcetrail
 
 		return nameHierarchy;
 	}
+
+	std::string serializeNameHierarchyToDatabaseString(const NameHierarchy& nameHierarchy)
+	{
+		static std::string META_DELIMITER = "\tm";
+		static std::string NAME_DELIMITER = "\tn";
+		static std::string PARTS_DELIMITER = "\ts";
+		static std::string SIGNATURE_DELIMITER = "\tp";
+
+		std::string serialized = nameHierarchy.nameDelimiter + META_DELIMITER;
+		for (size_t i = 0; i < nameHierarchy.nameElements.size(); i++)
+		{
+			if (i != 0)
+			{
+				serialized += NAME_DELIMITER;
+			}
+			const NameElement& nameElement = nameHierarchy.nameElements[i];
+			serialized += nameElement.name + PARTS_DELIMITER + nameElement.prefix + SIGNATURE_DELIMITER + nameElement.postfix;
+		}
+		return serialized;
+	}
 }

core/src/SourcetrailDBWriter.cpp

@@ -44,6 +44,10 @@ namespace sourcetrail
 	{
 	}
 
+	SourcetrailDBWriter::~SourcetrailDBWriter()
+	{
+	}
+
 	std::string SourcetrailDBWriter::getVersionString() const
 	{
 		return VERSION_STRING;