New methods of Manager added, and document improved.

libtocc/docs/source/api_reference.rst

@@ -29,6 +29,29 @@ To work with *libtocc*, you need to create an instance of this class.
 ``base_path`` is the absolute path to where Tocc should keep its files. (the
 tocc-managed file system.) Note that it have to be absolute.
 
+**Note:** Instances of ``libtocc::Manager`` are NOT thread-safe. In other
+words, you shouldn't share instances of it between threads. If you want
+to work multi-threaded, each of the threads should instanciate their own
+``libtocc::Manager``.
+
+.. function:: void libtocc::Manager::initialize()
+
+Initializes the *base_path* (the path provided in constructor).
+
+This will create the database in the *base_path*, and creates the required
+collections inside of it. This should be called once for each *base_path*,
+or else you can't work with it.
+
+Note that this shouldn't be called more than once for the same *base_path*.
+You will receive an exception if you do so.
+
+**Note:** Your application shouldn't automatically initialize every path it
+receive from the user. User may enter a wrong path by mistake, and your
+application silently initialize that path and, for example, imports user's
+files somewhere they didn't really want to. And their files will be lost.
+Instead, tell your users to run ``tocc-initialize`` on the path manually,
+or provide a function to let them do it manually from your application.
+
 
 .. function:: libtocc::FileInfo \
                 libtocc::Manager::get_file_info(const char* file_id)
@@ -61,6 +84,30 @@ It returns the information of the newly copied file.
 Another overload of ``import_file``. Same as the previous function, but it also
 accepts ``tags``. These tags will be assign to the copied file.
 
+.. function:: void libtocc::Manager::remove_file(const char* file_id)
+
+Deletes the specified file, both from the database and file system.
+
+``file_id`` is the ID of the file to be removed. ID of files can be gained
+by :cpp:func:`libtocc::FileInfo::get_id` method.
+
+.. function:: void libtocc::Manager::remove_file(FileInfo& file_to_remote)
+
+Overload of the previous function, which accepts a
+:cpp:class:`libtocc::FileInfo` instead of the file ID.
+
+.. function:: void libtocc::Manager::remove_files(const char* file_ids[], int file_ids_size)
+
+Deletes a list of files from the file system and the database.
+
+``file_ids`` is an array of files IDs to be removed. ``file_ids_size`` is the size of that
+array.
+
+.. function:: void libtocc::Manager::remove_files(FileInfoCollection& files_to_remove)
+
+Overload of the previous function, which accepts an instance of
+:cpp:class:`libtocc::FileInfoCollection` instead of an array of IDs.
+
 .. function:: void libtocc::Manager::assign_tags(const char* file_ids[], \
                 int file_ids_size, \
                 const TagsCollection* tags)
@@ -82,26 +129,49 @@ Overload of the previous function that accepts a file and a list of tags.
 
 Overload of the previous function that accepts a single file and a single tag.
 
-.. function:: void libtocc::Manager::remove_file(const char* file_id)
+.. function:: void libtocc::Manager::unassign_tag(const char* file_id, const char* tag)
 
-Removes the file that its ID is ``file_id``.
+Unassign a tag from the specified file.
 
-.. function:: void libtocc::Manager::remove_files(const char* file_ids[], int file_ids_size)
+``file_id`` is the file to unassign the tag from it. ``tag`` is the tag to unassign.
+
+.. function:: void libtocc::Manager::unassign_tags(const char* file_ids[], int file_ids_size, const TagsCollection* tags)
 
-Removes an array of files.
+Overload of the previous method, which accepts a list of files and a
+list of tags. It unassign all of the specified tags from all of the
+specified files.
 
-``file_ids`` is an array of IDs of files to remove. ``file_id_size`` is
+``file_id_size`` is
 the size of the ``file_ids`` array. If you pass zero or a negative number as
 ``file_id_size``, the method itself will calculate the size. If you have the
 size in your hand, it's better to pass it.
 
-.. function:: void libtocc::Manager::remove_file(FileInfo& file_to_remove)
+.. function:: void libtocc::Manager::unassign_tags(const char* file_id, const TagsCollection* tags)
 
-Removes the specified file.
+Overloads of the previous method, which accepts an instance of
+:cpp:class:`libtocc::TagsCollection` instead of an array of tags.
 
-.. function:: void libtocc::Manager::remove_files(FileInfoCollection& files_to_remove)
+.. function:: FileInfoCollection libtocc::Manager::search_files(Query& query)
+
+Executes the specified query, and returns all of the files that matches with it.
+
+It returns an empty collection if nothing found.
+
+See also :cpp:class:`libtocc::Query`.
+
+.. function:: TagStatisticsCollection libtocc::Manager::get_tags_statistics()
+
+Returns a list of tags that are available in database, and number of files
+each tag assigned to.
 
-Removes all the files in the specified collection.
+.. function:: TagStatisticsCollection libtocc::Manager::get_tags_statistics(const char* file_ids[], int file_ids_size)
+
+Overload of the previous method, which only returns statistics of the specified
+files. It means, it returns all the tags that are assigned to these files, and
+number of files assigned to these tags.
+
+``file_ids`` is an array of file IDs to get their statistics. ``file_ids_size``
+is the size of that array.
 
 .. function:: void libtocc::Manager::set_titles(const char* file_ids[], int file_ids_size, const char* new_title)
 
@@ -124,23 +194,23 @@ This class keeps information about a file.
 Normally, you don't need to create an instance of this class. This is the
 return type of some of the API methods.
 
-.. function:: const char* get_id() const
+.. function:: const char* libtocc::FileInfo::get_id() const
 
 Returns ID of the file.
 
-.. function:: TagsCollection get_tags() const
+.. function:: TagsCollection libtocc::FileInfo::get_tags() const
 
 Returns a list of tags that are assigned to the file.
 
-.. function:: const char* get_title() const
+.. function:: const char* libtocc::FileInfo::get_title() const
 
 Returns title of the file.
 
-.. function:: const char* get_traditional_path() const
+.. function:: const char* libtocc::FileInfo::get_traditional_path() const
 
 Returns traditional path of the file.
 
-.. function:: const char* get_physical_path() const
+.. function:: const char* libtocc::FileInfo::get_physical_path() const
 
 Returns physical path of the file (where file exists on the Tocc-managed
 file system).
@@ -174,9 +244,11 @@ This class keeps a list of tags.
 *Available in libtocc/front_end/file_info.h*
 
 .. class:: libtocc::TagsCollection
+
 Construct an empty collection.
 
 .. class:: libtocc::TagsCollection(const char* tags[], int size=-1)
+
 Constructs a collection of tags with specified tags in it.
 
 ``tags`` is the array of tags to initialize collection with. ``size`` is the
@@ -185,21 +257,27 @@ method itself calculates the size. But if you have the size in hand, you better
 pass it.
 
 .. class:: libtocc::TagsCollection(int size)
+
 Constructs a collection of tags. ``size`` will be reserve.
 
 .. function:: void libtocc::TagsCollection::add_tag(const char* tag)
+
 Adds a tag to the collection.
 
 .. function:: void libtocc::TagsCollection::remove_tag(const char* tag)
+
 Removes the specified tag from the collection.
 
 .. function:: bool libtocc::TagsCollection::contains(const char* tag)
+
 Returns true if the tag exists in the collection.
 
 .. function:: int libtocc::TagsCollection::size() const
+
 Returns number of elements in the collection.
 
 .. function:: bool libtocc::TagsCollection::is_empty() const
+
 Returns true if the collection is empty.
 
 
@@ -225,20 +303,25 @@ Iterator of the TagsCollection. Usage example::
 
 
 .. class:: libtocc::TagsCollection::Iterator(const libtocc::TagsCollection* collection)
+
 Creates an iterator. ``collection`` is the collection to iterate over.
 
-.. function:: void libtocc::TagsCollection::next()
+.. function:: void libtocc::TagsCollection::Iterator::next()
+
 Moves to the next element. (This also can be done using ``++`` operator.)
 
-.. function:: bool libtocc::TagsCollection::is_finished()
+.. function:: bool libtocc::TagsCollection::Iterator::is_finished()
+
 Returns true if ends of the iteration reached.
 
-.. function:: const char* libtocc::TagsCollection::get()
+.. function:: const char* libtocc::TagsCollection::Iterator::get()
+
 Gets the tag that iterator points to.
 It will be NULL if iterator passed end of the collection.
 (This method is equal to ``*`` operator.)
 
-.. function:: void libtocc::TagsCollection::reset()
+.. function:: void libtocc::TagsCollection::Iterator::reset()
+
 Resets the iterator. (Iterator will be points to the first element).
 
 

libtocc/docs/source/index.rst

@@ -79,11 +79,14 @@ Put it in ``sample.cpp`` file, and then simply compile it::
 against the ``libunqlite.so``. Because *libtocc* depends on it.
 
 Here's an explanation of what happened. First, you need to include
-``libtocc/manager.h`` which defines :cpp:class:`libtocc::Manager`, the
+``libtocc.h`` which defines :cpp:class:`libtocc::Manager`, the
 interface of the *libtocc*. All of the Tocc functionalities
 are accessible through Manager class. In its constructor, it gets a path to a
 directory that it should keeps its files and database. After that, we invoked
-the :cpp:func:`libtocc::Manager::import_file` method in order to copy a file from
+the :cpp:func:`libtocc::Manager::initialize` method. It will initialized the
+path we passed to the *Manager* constructor.
+Now, we can import files using :cpp:func:`libtocc::Manager::import_file` method.
+It will copy a file from
 the traditional file system to the tocc-managed file system. It's a photo, and
 its title is "A Beautiful Portrate".