diff --git a/core/include/SourcetrailDBWriter.h b/core/include/SourcetrailDBWriter.h index 8c7a6a1..82461e6 100644 --- a/core/include/SourcetrailDBWriter.h +++ b/core/include/SourcetrailDBWriter.h @@ -30,62 +30,397 @@ namespace sourcetrail { - class DatabaseStorage; // forward declaration prevents leakage of sqlite include dependency to users of the SourcetrailDBWriter + class DatabaseStorage; // forward declaration prevents leakage of sqlite include dependency to users + // of the SourcetrailDBWriter /** * Class wrapping the main interface for writing data to a Sourcetrail project database. * - * TODO: write a detailed description here. - * TODO: document all public interface methods - * TODO: add small example for usage here + * This class can be used to manage a Sourcetrail database file and to write information to such + * a file. + * + * The following code snippet illustrates a very basic usage of the SourcetrailDBWriter class: + * + * sourcetrail::SourcetrailDBWriter writer; + * writer.open("MyProject.srctrldb"); + * writer.recordSymbol({ "::",{ { "void", "foo", "()" } } }); + * writer.close(); */ class SourcetrailDBWriter { public: SourcetrailDBWriter(); + /** + * Provides the version of the SourcetrailDB Core as string with format "v1_db20_p0" + * + * The first number (e.g. "v1") of the version string denotes the interface version of the + * API. This version is increases on change that breaks the backwards compatibility. + * The second number (e.g. "db20") of the version string denotes the version of the database + * that will be generated by this class. This version needs to match the database version of + * the used Sourcetrail version to be compatible. + * The third number (e.g. "p0") is the patch number of the build and will increase with + * release that delivers bugfixes and features that don't break any compatibility. + */ std::string getVersionString() const; + /** + * Provides the supported database version as integer + * + * See getVersionString() for details + */ int getSupportedDatabaseVersion() const; + + /** + * Provides the last error that occurred while using the SourcetrailDBWriter + * + * The last error is empty if no error occurred since instantiation of the class or since the + * error has last been cleared. + * + * See: clearLastError() + */ const std::string& getLastError() const; + + /** + * Modifies the stored error message + * + * See: getLastError() + */ void setLastError(const std::string& error) const; + + /** + * Clears the stored error message + * + * See: getLastError() + */ void clearLastError(); + /** + * Opens a Sourcetrail database + * + * 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() + * can be checked for more detailed information. + */ 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() + * can be checked for more detailed information. + * + * 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() + * can be checked for more detailed information. + * + * 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 + * 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 + * database version. + * + * See: getSupportedDatabaseVersion() + * See: getLoadedDatabaseVersion() + */ bool isCompatible() const; + + /** + * Provides the database version of the loaded database file as an integer + */ int getLoadedDatabaseVersion() const; + /** + * Starts a database transaction on the currently open database + * + * Apart from allowing to restore the database to the state it was in before this method has + * 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() + * can be checked for more detailed information. + * + * See: commitTransaction() + * 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() + * 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() + * 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() + * can be checked for more detailed information. + */ bool optimizeDatabaseMemory(); - /// will return the same id for the same name hierarchy. will return 0 on failure. 0 is not a valid symbol id + /** + * Stores a symbol to the database + * + * Param nameHierarchy - the name of the symbol to store. + * Returns an integer id of the stored 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 + * the invalid id 0 is returned and getLastError() can be checked for more detailed information. + * + * See: NameHierarchy + */ int recordSymbol(const NameHierarchy& nameHierarchy); + + /** + * Stores a definition kind for a specific symbol to the database + * + * Calling this method allows to store a DefinitionKind (e.g. explicitly defined, implicitly + * defined) for a symbol referenced by id to the database. Calling this method with the same + * symbolId multiple times overwrites the symbol's previously recorded DefinitionKind. If no + * DefinitionKind is recorded for a symbol, Sourcetrail treats this symbol as "non-indexed". + * 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 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 + */ bool recordSymbolDefinitionKind(int symbolId, DefinitionKind definitionKind); + + /** + * Stores a symbol kind for a specific symbol to the database + * + * Calling this method allows to store a SymbolKind (e.g. "class", "function", etc.) for a + * symbol referenced by id to the database. Calling this method with the same symbolId multiple + * 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 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 + */ bool recordSymbolKind(int symbolId, SymbolKind symbolKind); - /// The provided "location" will be clickable and displayable. When clicked it will cause the symbol with the specified "symbolId" to be activated. When - /// the symbol with the specified "symbolId" is activated, this location will be displayed. + + /** + * Stores a location for a specific symbol to the database + * + * This method allows to store a location for a symbol referenced by id to the database. + * Calling this method with the same symbolId multiple times adds multiple locations for the + * respective symbol. The stored location will be clickable and displayable. When clicked + * 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 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 + */ bool recordSymbolLocation(int symbolId, const SourceRange& location); - /// The provided "location" will be displayable. When the symbol with the specified "symbolId" is activated, this location will be displayed. + + /** + * Stores a scope location for a specific symbol to the database + * + * 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 + * by Sourcetrail. + * + * 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 + * symbol. + * Returns true if the operation was successful. Otherwise false is returned and getLastError() + * can be checked for more detailed information. + * + * See: SourceRange + */ bool recordSymbolScopeLocation(int symbolId, const SourceRange& location); + + /** + * 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 + * locations for the respective symbol. Sourcetrail will only make use of one of the recorded + * signature locations, so please try to call this method only once. + * If a signature location is recorded for a symbol, Sourcetrail will display the respective + * 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. + * Param location - the SourceRange that shall be recorded as signature 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 + */ bool recordSymbolSignatureLocation(int symbolId, const SourceRange& location); + /** + * Stores a reference between two symbols to the database + * + * 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 + * description in the hover tooltip of the edge. + * + * 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 + * 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 + */ int recordReference(int contextSymbolId, int referencedSymbolId, ReferenceKind referenceKind); + + /** + * Stores a location for a specific reference to the database + * + * This method allows to store a location for a reference to the database. + * Calling this method with the same referenceId multiple times adds multiple locations for the + * respective reference. The stored location will be clickable and displayable. When the reference + * location is clicked Sourcetrail will activate the symbol referenced by the respective reference. + * 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 location - the SourceRange that shall be recorded as location for the respective reference. + * Returns true if the operation was successful. Otherwise false is returned and getLastError() + * can be checked for more detailed information. + * + * 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. + * Returns an integer id of the stored file. 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. + */ int recordFile(const std::string& filePath); + + /** + * Stores language information for a specific file to the database + * + * This method allows to store language information for a file to the database. Language information + * 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 languageIdentifier - a string that denotes the programming language the respective file + * is written in. + * Returns true if the operation was successful. Otherwise false is returned and getLastError() + * can be checked for more detailed information. + */ 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 + * of the local symbol's definition). + * 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 + * the invalid id 0 is returned and getLastError() can be checked for more detailed information. + */ int recordLocalSymbol(const std::string& name); + + /** + * Stores a location for a specific local symbol to the database + * + * This method allows to store a location for a local symbol symbol referenced by id to the database. + * Calling this method with the same symbolId multiple times adds multiple locations for the + * respective local symbol. The stored location will be clickable and displayable. When clicked + * 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 location - the SourceRange that shall be recorded as location for the respective + * local symbol. + * Returns true if the operation was successful. Otherwise false is returned and getLastError() + * can be checked for more detailed information. + * + * See: SourceRange + */ bool recordLocalSymbolLocation(int localSymbolId, const SourceRange& location); + /** + * Stores a comment location to the database + * + * 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. + * Returns true if the operation was successful. Otherwise false is returned and getLastError() + * can be checked for more detailed information. + * + * See: SourceRange + */ bool recordCommentLocation(const SourceRange& location); + /** + * Stores an indexing error to the database + * + * This method allows to store an indexing error to the database. Errors will be shown by + * 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 fatal - boolean that tells Sourcetrail if this is a fatal error. + * 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 + */ bool recordError(const std::string& message, bool fatal, const SourceRange& location); private: