added comments and an execute function

include/sonata/Admin.hpp

@@ -9,56 +9,151 @@ namespace sonata {
 
 class AdminImpl;
 
+/**
+ * @brief Admin interface to a Sonata service. Enables creating
+ * and destroying databases, and attaching and detaching them
+ * from a provider. If Sonata providers have set up a security
+ * token, operations from the Admin interface will need this
+ * security token.
+ */
 class Admin {
 
     public:
 
+    /**
+     * @brief Constructor.
+     *
+     * @param engine Thallium engine.
+     * @param token Security token setup by providers.
+     */
     Admin(thallium::engine& engine, const std::string& token);
     
+    /**
+     * @brief Copy constructor.
+     */
     Admin(const Admin&);
 
+    /**
+     * @brief Move constructor.
+     */
     Admin(Admin&&);
 
+    /**
+     * @brief Copy-assignment operator.
+     */
     Admin& operator=(const Admin&);
 
+    /**
+     * @brief Move-assignment operator.
+     */
     Admin& operator=(Admin&&);
 
+    /**
+     * @brief Destructor.
+     */
     ~Admin();
 
+    /**
+     * @brief Check if the Admin instance is valid.
+     */
     operator bool() const;
     
+    /**
+     * @brief Creates a database on the target provider.
+     * The config string must be a JSON object acceptable
+     * by the desired backend's creation function.
+     *
+     * @param address Address of the target provider.
+     * @param provider_id Provider id.
+     * @param name Name of the database to create.
+     * @param type Type of the database to create.
+     * @param config JSON configuration for the database.
+     */
     void createDatabase(const std::string& address,
                         uint16_t provider_id,
                         const std::string& name,
                         const std::string& type,
                         const std::string& config) const;
 
+    /**
+     * @brief Creates a database on the target provider.
+     * The config object must be a JSON object acceptable
+     * by the desired backend's creation function.
+     *
+     * @param address Address of the target provider.
+     * @param provider_id Provider id.
+     * @param name Name of the database to create.
+     * @param type Type of the database to create.
+     * @param config JSON configuration for the database.
+     */
     void createDatabase(const std::string& address,
                         uint16_t provider_id,
                         const std::string& name,
                         const std::string& type,
                         const Json::Value& config) const;
 
+    /**
+     * @brief Attaches an existing database to the target provider.
+     * The config string must be a JSON object acceptable
+     * by the desired backend's attach function.
+     *
+     * @param address Address of the target provider.
+     * @param provider_id Provider id.
+     * @param name Name of the database to create.
+     * @param type Type of the database to create.
+     * @param config JSON configuration for the database.
+     */
     void attachDatabase(const std::string& address,
                         uint16_t provider_id,
                         const std::string& name,
                         const std::string& type,
                         const std::string& config) const;
 
+    /**
+     * @brief Attaches an existing database to the target provider.
+     * The config object must be a JSON object acceptable
+     * by the desired backend's attach function.
+     *
+     * @param address Address of the target provider.
+     * @param provider_id Provider id.
+     * @param name Name of the database to create.
+     * @param type Type of the database to create.
+     * @param config JSON configuration for the database.
+     */
     void attachDatabase(const std::string& address,
                         uint16_t provider_id,
                         const std::string& name,
                         const std::string& type,
                         const Json::Value& config) const;
 
+    /**
+     * @brief Detach an attached database from the target provider.
+     *
+     * @param address Address of the target provider.
+     * @param provider_id Provider id.
+     * @param name Name of the database to detach.
+     */
     void detachDatabase(const std::string& address,
                         uint16_t provider_id,
                         const std::string& name) const;
 
+    /**
+     * @brief Destroys an attached database from the target provider.
+     *
+     * @param address Address of the target provider.
+     * @param provider_id Provider id.
+     * @param name Name of the database to destroy.
+     */
     void destroyDatabase(const std::string& address,
                          uint16_t provider_id,
                          const std::string& name) const;
 
+    /**
+     * @brief Shuts down the target server. The Thallium engine
+     * used by the server must have remote shutdown enabled.
+     *
+     * @param address Address of the server to shut down.
+     */
     void shutdownServer(const std::string& address) const;
 
     private:

include/sonata/Backend.hpp

@@ -2,74 +2,227 @@
 #define __SONATA_BACKEND_HPP
 
 #include <sonata/RequestResult.hpp>
+#include <unordered_set>
 #include <unordered_map>
 #include <functional>
 #include <json/json.h>
 
+/**
+ * @brief Helper class to register backend types into the backend factory.
+ */
 template<typename BackendType>
 class __SonataBackendRegistration;
 
 namespace sonata {
 
+/**
+ * @brief Interface for database backends. To build a new backend,
+ * implement a class that inherits from Backend, and put
+ * SONATA_REGISTER_BACKEND(mybackend, MyBackend); in a cpp file
+ * that includes your backend class' header file.
+ *
+ * Your backend class should also have two static functions to
+ * respectively create and open a backend database:
+ *
+ * std::unique_ptr<Backend> create(const Json::Value& config)
+ * std::unique_ptr<Backend> attach(const Json::Value& config)
+ */
 class Backend {
     
     public:
 
+    /**
+     * @brief Constructor.
+     */
     Backend() = default;
 
+    /**
+     * @brief Move-constructor.
+     */
     Backend(Backend&&) = default;
 
+    /**
+     * @brief Copy-constructor.
+     */
     Backend(const Backend&) = default;
 
+    /**
+     * @brief Move-assignment operator.
+     */
     Backend& operator=(Backend&&) = default;
 
+    /**
+     * @brief Copy-assignment operator.
+     */
     Backend& operator=(const Backend&) = default;
 
+    /**
+     * @brief Destructor.
+     */
     virtual ~Backend() = default;
 
+    /**
+     * @brief Executes Jx9 code on the Database. The variable 
+     * names specified in vars will then be extracted and returned.
+     *
+     * @param code Code to execute.
+     * @param vars Variables to return.
+     *
+     * @return a RequestResult<std::unordered_map<std::string,std::string>>
+     * instance.
+     */
+    virtual RequestResult<std::unordered_map<std::string,std::string>>
+        execute(const std::string& code,
+                const std::unordered_set<std::string>& vars) = 0;
+
+    /**
+     * @brief Creates a new collection in the database.
+     *
+     * @param coll_name Name of the collection.
+     *
+     * @return a RequestResult<bool> instance.
+     */
     virtual RequestResult<bool> createCollection(
             const std::string& coll_name) = 0;
 
+    /**
+     * @brief Checks if a collection exists.
+     *
+     * @param coll_name Name of the collection.
+     *
+     * @return a RequestResult<bool> instance.
+     */
     virtual RequestResult<bool> openCollection(
             const std::string& coll_name) = 0;
 
+    /**
+     * @brief Destroys a collection
+     *
+     * @param coll_name Name of the collection.
+     *
+     * @return a RequestResult<bool> instance.
+     */
     virtual RequestResult<bool> dropCollection(
             const std::string& coll_name) = 0;
 
+    /**
+     * @brief Stores a record into the collection.
+     * The record should be a valid JSON object.
+     *
+     * @param coll_name Name of the collection.
+     * @param record Record to store.
+     *
+     * @return a RequestResult<uint64_t> instance
+     * containing the record id if successful.
+     */
     virtual RequestResult<uint64_t> store(
             const std::string& coll_name,
             const std::string& record) = 0;
 
+    /**
+     * @brief Fetches a particular record by its id.
+     *
+     * @param coll_name Name of the collection.
+     * @param record_id Record id.
+     *
+     * @return a RequestResult<std::string> instance.
+     * containing the content of the record if successful.
+     */
     virtual RequestResult<std::string> fetch(
             const std::string& coll_name,
             uint64_t record_id) = 0;
 
+    /**
+     * @brief Returns an array of records matching a give
+     * Jx9 filter. The filter should be expressed as a string
+     * containing a function. For example:
+     *
+     * "function($user) { return $user.age > 30; }"
+     *
+     * @param coll_name Name of the collection.
+     * @param filter_code Code of the Jx9 function.
+     *
+     * @return a RequestResult<std::vector<std::string>>
+     * instance containing the result of the request.
+     */
     virtual RequestResult<std::vector<std::string>> filter(
             const std::string& coll_name,
             const std::string& filter_code) = 0;
 
+    /**
+     * @brief Updates an existing record with the new content.
+     *
+     * @param coll_name Name of the collection.
+     * @param record_id Record to update.
+     * @param new_content New content of the record.
+     *
+     * @return a RequestResult<bool> instance indicating
+     * whether the update was successful.
+     */
     virtual RequestResult<bool> update(
             const std::string& coll_name,
             uint64_t record_id,
             const std::string& new_content) = 0;
 
+    /**
+     * @brief Returns all the records in the collection.
+     *
+     * @param coll_name Name of the collection.
+     *
+     * @return a RequestResult<std::vector<std::string>> instance
+     * containing all the records as strings, if successful.
+     */
     virtual RequestResult<std::vector<std::string>> all(
             const std::string& coll_name) = 0;
 
+    /**
+     * @brief Returns the last record id stored in the collection.
+     *
+     * @param coll_name Name of the collection.
+     *
+     * @return a RequestResult<uint64_t> instance containing
+     * the last record id, if successful.
+     */
     virtual RequestResult<uint64_t> lastID(
             const std::string& coll_name) = 0;
 
+    /**
+     * @brief Returns the size of the collection.
+     *
+     * @param coll_name Name of the collection.
+     *
+     * @return a RequestResult<size_t> instance containing
+     * the size of the collection.
+     */
     virtual RequestResult<size_t> size(
             const std::string& coll_name) = 0;
 
+    /**
+     * @brief Erases the specified record from the collection.
+     *
+     * @param coll_name Name of the collection.
+     * @param record_id Record to erase.
+     *
+     * @return a RequestResult<bool> instance.
+     */
     virtual RequestResult<bool> erase(
             const std::string& coll_name,
             uint64_t record_id) = 0;
 
+    /**
+     * @brief Destroys the underlying database resources.
+     *
+     * @return a RequestResult<bool> instance indicating
+     * whether the database was successfully destroyed.
+     */
     virtual RequestResult<bool> destroy() = 0;
 
 };
 
+/**
+ * @brief The BackendFactory contains function to create
+ * or attach databases.
+ */
 class BackendFactory {
 
     template<typename BackendType>
@@ -79,9 +232,27 @@ class BackendFactory {
 
     BackendFactory() = delete;
 
+    /**
+     * @brief Creates a database and returns a unique_ptr to the created 
+     * backend instance.
+     *
+     * @param backend_name Name of the backend to use.
+     * @param config Configuration object to pass to the backend's create function.
+     *
+     * @return a unique_ptr to the created Backend.
+     */
     static std::unique_ptr<Backend> createBackend(const std::string& backend_name,
                                                   const Json::Value& config);
 
+    /**
+     * @brief Opens an existing database and returns a unique_ptr to the
+     * created backend instance.
+     *
+     * @param backend_name Name of the backend to use.
+     * @param config Configuration object to pass to the backend's attach function.
+     *
+     * @return a unique_ptr to the created Backend.
+     */
     static std::unique_ptr<Backend> attachBackend(const std::string& backend_name,
                                                   const Json::Value& config);
 

include/sonata/Client.hpp

@@ -9,26 +9,63 @@ namespace sonata {
 
 class ClientImpl;
 
+/**
+ * @brief The Client object is the main object used to establish
+ * a connection with a Sonata service.
+ */
 class Client {
 
     public:
 
+    /**
+     * @brief Constructor.
+     *
+     * @param engine Thallium engine.
+     */
     Client(thallium::engine& engine);
     
+    /**
+     * @brief Copy constructor.
+     */
     Client(const Client&);
 
+    /**
+     * @brief Move constructor.
+     */
     Client(Client&&);
 
+    /**
+     * @brief Copy-assignment operator.
+     */
     Client& operator=(const Client&);
 
+    /**
+     * @brief Move-assignment operator.
+     */
     Client& operator=(Client&&);
 
+    /**
+     * @brief Destructor.
+     */
     ~Client();
 
+    /**
+     * @brief Opens a remote database and returns a
+     * Database instance to access it.
+     *
+     * @param address Address of the provider holding the database.
+     * @param provider_id Provider id.
+     * @param db_name Database name.
+     *
+     * @return a Database instance.
+     */
     Database open(const std::string& address, 
                   uint16_t provider_id,
                   const std::string& db_name) const;
 
+    /**
+     * @brief Checks that the Client instance is valid.
+     */
     operator bool() const;
 
     private:

include/sonata/Collection.hpp

@@ -12,67 +12,199 @@ namespace tl = thallium;
 class DatabaseImpl;
 class CollectionImpl;
 
+/**
+ * @brief The Collection object is a handle to a collection
+ * in a given remote database on a server. It offers function
+ * to store and search documents.
+ */
 class Collection {
 
     friend class Database;
 
     public:
     
+    /**
+     * @brief Copy constructor.
+     */
     Collection(const Collection&);
 
+    /**
+     * @brief Move constructor.
+     */
     Collection(Collection&&);
 
+    /**
+     * @brief Copy-assignment operator.
+     */
     Collection& operator=(const Collection&);
 
+    /**
+     * @brief Move-assignment operator.
+     */
     Collection& operator=(Collection&&);
 
+    /**
+     * @brief Destructor.
+     */
     ~Collection();
 
+    /**
+     * @brief Checks if the Collection object is valid.
+     */
     operator bool() const;
 
+    /**
+     * @brief Stores a document into the collection.
+     *
+     * @param record A valid JSON-formated document.
+     *
+     * @return the record id of the stored document.
+     */
     uint64_t store(const std::string& record) const;
 
+    /**
+     * @brief Stores a document into the collection.
+     *
+     * @param record A JSON object.
+     *
+     * @return the record id of the stored document.
+     */
     uint64_t store(const Json::Value& record) const;
 
+    /**
+     * @brief Stores a document into the collection.
+     *
+     * @param record A valid JSON-formated document.
+     *
+     * @return the record id of the stored document.
+     */
     uint64_t store(const char* record) const {
         return store(std::string(record));
     }
 
+    /**
+     * @brief Fetches a document by its record id.
+     *
+     * @param[in] id Record id.
+     * @param[out] result Resulting string.
+     */
     void fetch(uint64_t id,
                std::string* result) const;
 
+    /**
+     * @brief Fetches a document by its record id.
+     *
+     * @param[in] id Record id.
+     * @param[out] result Resulting JSON object.
+     */
     void fetch(uint64_t id,
                Json::Value* result) const;
 
+    /**
+     * @brief Filters the collection and returns the
+     * records that match the condition. This condition should
+     * be expressed as a Jx9 function returning TRUE or FALSE.
+     * For example the following Jx9 function selects only
+     * the records where x < 4 :
+     *
+     * "function($record) { return $record.x < 4; }"
+     *
+     * @param filterCode A Jx9 filter code.
+     * @param result Resuling vector of records as strings.
+     */
     void filter(const std::string& filterCode,
                 std::vector<std::string>* result) const;
 
+    /**
+     * @brief Filters the collection and returns the
+     * records that match the condition. This condition should
+     * be expressed as a Jx9 function returning TRUE or FALSE.
+     * For example the following Jx9 function selects only
+     * the records where x < 4 :
+     *
+     * "function($record) { return $record.x < 4; }"
+     *
+     * @param filterCode A Jx9 filter code.
+     * @param result Resuling JSON object containing the array of results.
+     */
     void filter(const std::string& filterCode,
                 Json::Value* result) const;
 
+    /**
+     * @brief Updates the content of a document with a new content.
+     *
+     * @param id Record id of the document to update.
+     * @param record New document.
+     */
     void update(uint64_t id,
                 const Json::Value& record) const;
 
+    /**
+     * @brief Updates the content of a document with a new content.
+     *
+     * @param id Record id of the document to update.
+     * @param record New document.
+     */
     void update(uint64_t id,
                 const std::string& record) const;
 
+    /**
+     * @brief Updates the content of a document with a new content.
+     *
+     * @param id Record id of the document to update.
+     * @param record New document.
+     */
     void update(uint64_t id,
                 const char* record) const {
         return update(id, std::string(record));
     }
 
+    /**
+     * @brief Returns all the documents from the collection
+     * as a vector of strings.
+     *
+     * @param result All the documents from the collection.
+     */
     void all(std::vector<std::string>* result) const;
 
+    /**
+     * @brief Returns all the documents from the collection
+     * as a JSON object.
+     *
+     * @param result All the documents from the collection.
+     */
     void all(Json::Value* result)