Private API documentation, win32 msvc port

Index: src/libdar/cache.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/cache.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/cache.hpp	18 Feb 2005 11:08:23 -0000	1.1.3.1
+++ src/libdar/cache.hpp	21 Mar 2005 21:11:33 -0000	1.3
@@ -33,32 +33,35 @@
 #include "infinint.hpp"
 #include "generic_file.hpp"
 
 namespace libdar
 {
-	/// the cache class implements a very basic read/write caching mechanisme
-
-	/// it is intended to reduce context switches when no compression is used
-	/// and when reading or writing catalogue through a pipe. The catalogue
-	/// read and write is done by calling dump/constructor methods of the many
-	/// objects that a catalogue can contain. This makes a lot of small read
-    	/// or write, which make very poor performances when used over the network
-	/// through a pipe to ssh. When compression is used, the problem disapears
-	/// as the compression engine gather theses many small read or write into
-	/// much bigger ones. This in only when there is no compression that
-	/// that this class is useful (and used).
-	/// \ingroup Private
+	
+	
+	/// The cache class implements a very basic read/write caching mechanism.
+
+	/// It is intended to reduce context switches when no compression is used.
+	/// In particular, it is used when reading or writing catalogue through a
+	/// pipe. Catalogue read and writes are done when dump or constructor
+	/// methods are called on the many individual objects that a catalogue can
+	/// contain. This causes a lot of small reads and writes, which severely
+	/// degrades performance when used over a networkd or through an ssh pipe.
+	/// 
+	/// When compression is used, the problem disappears because 
+	/// the compression engine caches data itself. Thus, the cache class is
+	/// only used when compression is not used.
+	/// \ingroup Filters
     class cache : public generic_file
     {
     public:
 	cache(user_interaction & dialog,
 	      generic_file & hidden,
 	      U_I initial_size = 10240,
               U_I unused_read_ratio = 10, U_I observation_read_number = 100, U_I max_size_hit_read_ratio = 50,
 	      U_I unused_write_ratio = 10, U_I observation_write_number = 100, U_I max_size_hit_write_ratio = 50);
 	    // *** hidden: is the file to cache, it is never deleted by the cache object,
-	    // *** intial_size: is the initial size of the cache for reading (read this amount of data at a time)
+	    // *** initial_size: is the initial size of the cache for reading (read this amount of data at a time)
 	    // unused_read_ratio: is the ratio of cached data effectively asked for reading below which the cache size is divided by two
             //   in other words, if during observation_read_number fullfilment of the cache, less than unused_read_ratio percent of data has been
             //   effectively asked for reading, then the cache size is divided by two
             // *** max_size_hit_read_ratio: is the ratio above which the cache size is doubled. In other words, if during observation_read_number
 	    //   times of cache fullfilment, more than max_size_hit_read_ratio percent time all the cached data has been asked for reading
@@ -117,10 +120,11 @@
 
 	void flush_write();
 	void fulfill_read();
 	void clear_read() { if(read_mode) { buffer_cache.next = buffer_cache.last = 0; } };
     };
+    
 
 } // end of namespace
 
 #endif
 
Index: src/libdar/catalogue.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/catalogue.hpp,v
retrieving revision 1.1.3.2
retrieving revision 1.3
diff -U5 -r1.1.3.2 -r1.3
--- src/libdar/catalogue.hpp	2 Mar 2005 13:32:20 -0000	1.1.3.2
+++ src/libdar/catalogue.hpp	21 Mar 2005 21:11:33 -0000	1.3
@@ -48,17 +48,27 @@
 #include "compressor.hpp"
 #include "integers.hpp"
 #include "mask.hpp"
 #include "special_alloc.hpp"
 
+
+/// \defgroup Catalogue Catalogue objects
+/// \brief Classes representing the elements read and written to the catalogue.
+///
+/// TODO: Overview of catalogue objects
+
+
 namespace libdar
 {
     class file_etiquette;
     class entree;
 
 	/// \addtogroup Private
 	/// @{
+	
+	/// \addtogroup Catalogue
+	/// @{
 
     enum saved_status { s_saved, s_fake, s_not_saved };
 
     struct entree_stats
     {
@@ -745,9 +755,10 @@
 
         static const eod r_eod;           // needed to return eod reference, without taking risk of saturating memory
     };
 
 	/// @}
+	/// @}
 
 } // end of namespace
 
 #endif
Index: src/libdar/crypto.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/crypto.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/crypto.hpp	18 Feb 2005 11:08:28 -0000	1.1.3.1
+++ src/libdar/crypto.hpp	21 Mar 2005 21:11:33 -0000	1.3
@@ -58,11 +58,11 @@
     extern void crypto_split_algo_pass(const std::string & all, crypto_algo & algo, std::string & pass);
 
 	/// blowfish implementation of encryption
 
 	/// inherited class from tronconneuse class
-	/// \ingroup Private
+	/// \ingroup Filters
     class blowfish : public tronconneuse
     {
     public:
 	blowfish(user_interaction & dialog, U_32 block_size, const std::string & key, generic_file & encrypted_side);
 	    // destructor does not seems to be required for BF_KEY
Index: src/libdar/defile.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/defile.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/defile.hpp	18 Feb 2005 11:08:30 -0000	1.1.3.1
+++ src/libdar/defile.hpp	22 Mar 2005 16:13:38 -0000	1.3
@@ -40,11 +40,11 @@
 	/// the filter routines manipulates flow of inode, where their relative order
 	/// represent the directory structure. To be able to know what is the real path
 	/// of the current inode, all previously passed inode must be known.
 	/// this class is used to display the progression of the filtering routing,
 	/// and the file on which the filtering routine operates
-	/// \ingroup Private
+	/// \ingroup Structure
     class defile
     {
     public :
         defile(const path &racine) : chemin(racine) { init = true; };
 
Index: src/libdar/elastic.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/elastic.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/elastic.hpp	18 Feb 2005 11:08:27 -0000	1.1.3.1
+++ src/libdar/elastic.hpp	22 Mar 2005 16:13:38 -0000	1.3
@@ -45,11 +45,11 @@
 	/// the elastic buffer class
 
 	/// the elastic class makes possible to insert arbritrary bytes beside information bytes, and to
 	/// retreive later without any other knowledge which bytes are information and which byte are from the
 	/// elastic buffer. The main purpose is for strong encryption
-	/// \ingroup Private
+	/// \ingroup Filters
     class elastic
     {
     public:
 	elastic(U_32 size) { if(size == 0) throw Erange("elastic::elastic", gettext("zero is not a valid size for an elastic buffer")); taille = size; };
 	elastic(const char *buffer, U_32 size, elastic_direction dir);
Index: src/libdar/etage.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/etage.hpp,v
retrieving revision 1.1.3.2
retrieving revision 1.4
diff -U5 -r1.1.3.2 -r1.4
--- src/libdar/etage.hpp	2 Mar 2005 13:32:21 -0000	1.1.3.2
+++ src/libdar/etage.hpp	21 Mar 2005 21:11:33 -0000	1.4
@@ -35,27 +35,30 @@
 #include <string>
 #include "infinint.hpp"
 
 namespace libdar
 {
+	
+	
 
 	/// the etage structure keep trace of directory contents
 
 	/// it relies on the opendir() system call family than
 	/// cannot be used recursively. Thus each etage structure
 	/// contains the contents of a directory, and can then be stored beside
 	/// other etage structures corresponding to subdirectories
-	/// \ingroup Private
+	/// \ingroup Filesystem
     struct etage
     {
 	etage() { fichier.clear(); last_mod = 0; last_acc = 0; }; // required to fake an empty dir when one is impossible to open
         etage(user_interaction & ui, const char *dirname, const infinint & x_last_acc, const infinint & x_last_mod, bool cache_directory_tagging);
 
         bool read(std::string & ref);
 
         std::list<std::string> fichier;
         infinint last_mod, last_acc;
     };
+    
 
 } // end of namespace
 
 #endif
Index: src/libdar/filesystem.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/filesystem.hpp,v
retrieving revision 1.1.3.2
retrieving revision 1.4
diff -U5 -r1.1.3.2 -r1.4
--- src/libdar/filesystem.hpp	2 Mar 2005 13:32:26 -0000	1.1.3.2
+++ src/libdar/filesystem.hpp	21 Mar 2005 21:11:33 -0000	1.4
@@ -52,14 +52,23 @@
 #include <vector>
 #include "catalogue.hpp"
 #include "infinint.hpp"
 #include "etage.hpp"
 
+/// \defgroup Filesystem Backup filesystem interface
+/// \brief Interface with target filesystem where files are read and written to.
+///
+/// TODO: Overview of filesystem classes.
+
+
 namespace libdar
 {
 	/// \addtogroup Private
 	/// @{
+	
+	/// \addtogroup Filesystem
+	/// @{
 
 	/// keep trace of hard links when reading the filesystem
     class filesystem_hard_link_read
     {
             // this class is not to be used directly
@@ -274,9 +283,10 @@
         void detruire();
         void copy_from(const filesystem_restore & ref);
     };
 
 	/// @}
+	/// @}
 
 } // end of namespace
 
 #endif
Index: src/libdar/generic_file.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/generic_file.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/generic_file.hpp	18 Feb 2005 11:08:21 -0000	1.1.3.1
+++ src/libdar/generic_file.hpp	21 Mar 2005 21:11:33 -0000	1.3
@@ -43,10 +43,23 @@
 ///////////////////////////////////////////////////////////////////////
 // IMPORTANT : THIS FILE MUST ALWAYS BE INCLUDE AFTER infinint.hpp   //
 //             (and infinint.hpp must be included too, always)       //
 ///////////////////////////////////////////////////////////////////////
 
+
+/// \defgroup Archive Archive filesystem interface
+/// \brief Interface with filesystem for writing and reading archive files. This
+/// includes physical files and pipes.
+///
+/// TODO: Overview of filesystem classes.
+
+/// \defgroup Filters File filters
+/// \brief Data filters for reading and writing archive files. These classes
+/// overlay the archive filesystem interface.
+///
+/// TODO: Overview of filesystem classes.
+
 #include "../my_config.h"
 
 extern "C"
 {
 #if HAVE_UNISTD_H
@@ -70,22 +83,35 @@
     typedef char crc[CRC_SIZE];
     extern void clear(crc & value);
     extern void copy_crc(crc & dst, const crc & src);
     extern bool same_crc(const crc &a, const crc &b);
 
+
+	/// \addtogroup Archive
+	/// @{
+
 	/// generic_file openning modes
     enum gf_mode
     {
 	gf_read_only,  ///< read only access
 	gf_write_only, ///< write only access
 	gf_read_write  ///< read and write access
     };
 
-
+	/// \brief Translates filesystem mode to <code>gf_mode</code> indication.
     extern gf_mode generic_file_get_mode(S_I fd);
+    
+    /// \brief Translates <code>gf_mode</code> to localized string.
     extern const char * generic_file_get_name(gf_mode mode);
 
+    /// @}
+    
+    
+    /// \addtogroup Filters
+    /// @{
+    
+
 	/// this is the interface class from which all other data transfer classes inherit
 
 	/// it provides mainly read and write operations,
 	/// skip operations and few other functions.
 	/// \note
@@ -174,10 +200,15 @@
         S_I write_crc(char *a, size_t size);
 
 	void detruire() { if(gf_ui != NULL) delete gf_ui; };
 	void copy_from(const generic_file & ref);
     };
+    
+    /// @}
+
+	/// \addtogroup Archive
+	/// @{
 
 	/// this is a full implementation of a generic_file applied to a plain file
     class fichier : public generic_file, public thread_cancellation
     {
     public :
@@ -201,10 +232,15 @@
     private :
         S_I filedesc;
 
         void open(const char *name, gf_mode m);
     };
+    
+    /// @}
+    
+    /// \addtogroup Filters
+    /// @{
 
 #define CONTEXT_INIT "init"
 #define CONTEXT_OP   "operation"
 
 	/// the contextual class adds the information of phases in the generic_file
@@ -225,9 +261,10 @@
 	virtual void set_info_status(const std::string & s) = 0;
         virtual std::string get_info_status() const = 0;
     };
 
 	/// @}
+	/// @}
 
 } // end of namespace
 
 #endif
Index: src/libdar/header.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/header.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/header.hpp	18 Feb 2005 11:08:33 -0000	1.1.3.1
+++ src/libdar/header.hpp	21 Mar 2005 21:11:33 -0000	1.3
@@ -33,10 +33,15 @@
 #include "../my_config.h"
 #include "infinint.hpp"
 #include "generic_file.hpp"
 #include "user_interaction.hpp"
 
+
+/// \defgroup Structure Archive structure
+/// \brief Structures and functions for the archive file structure.
+/// \ingroup Private
+
 namespace libdar
 {
     const unsigned int LABEL_SIZE = 10;
 
     const char FLAG_NON_TERMINAL = 'N';
@@ -51,10 +56,12 @@
 
     extern void label_copy(label & left, const label & right);
     extern bool header_label_is_equal(const label &a, const label &b);
     extern void header_generate_internal_filename(label & ret);
 
+	/// \brief Slice header structure.
+	/// \ingroup Structure
     struct header
     {
         magic_number magic;
         label internal_name;
         char flag;
Index: src/libdar/null_file.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/null_file.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/null_file.hpp	18 Feb 2005 11:08:21 -0000	1.1.3.1
+++ src/libdar/null_file.hpp	21 Mar 2005 21:11:33 -0000	1.3
@@ -35,18 +35,19 @@
 #include "thread_cancellation.hpp"
 
 namespace libdar
 {
 
-	/// the null_file class implements the /dev/null behavior
+	/// The null_file class implements the behavior of /dev/null.
 
-	/// this is a generic_file implementation that emulate the
-	/// comportment of the /dev/null special file.
-	/// all that is writen to is lost, and nothing can be read from
-	/// it (empty file). This is a completed implementation all
-	/// call are consistent.
-	/// \ingroup Private
+	/// This is a generic_file implementation that emulates the
+	/// behavior of the /dev/null special file.
+	/// All data written to it is lost and nothing can be read from
+	/// it (like an empty file). This is written to ensure all calls
+	/// are consistent. Incompletely implemented classes can be stacked on
+	/// top of this class to catch all class method calls.
+	/// \ingroup Filters
 
     class null_file : public generic_file, public thread_cancellation
     {
     public :
         null_file(user_interaction & dialog, gf_mode m) : generic_file(dialog, m) {};
Index: src/libdar/scrambler.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/scrambler.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/scrambler.hpp	18 Feb 2005 11:08:24 -0000	1.1.3.1
+++ src/libdar/scrambler.hpp	22 Mar 2005 16:13:38 -0000	1.3
@@ -37,11 +37,11 @@
 
 namespace libdar
 {
 
 	/// \brief scrambler is a very weak encryption scheme
-	/// \ingroup Private
+	/// \ingroup Filters
 
     class scrambler : public generic_file
     {
     public:
         scrambler(user_interaction & dialog, const std::string & pass, generic_file & hidden_side);
Index: src/libdar/terminateur.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/terminateur.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/terminateur.hpp	18 Feb 2005 11:08:31 -0000	1.1.3.1
+++ src/libdar/terminateur.hpp	22 Mar 2005 16:13:38 -0000	1.3
@@ -40,11 +40,11 @@
 {
 
 	/// terminateur class indicates the location of the beginning of the catalogue
 
 	/// it is the last bytes sequence of an archive.
-	/// \ingroup Private
+	/// \ingroup Structure
 
     class terminateur
     {
     public :
         void set_catalogue_start(infinint xpos) { pos = xpos; };
Index: src/libdar/tronconneuse.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/tronconneuse.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/tronconneuse.hpp	18 Feb 2005 11:08:19 -0000	1.1.3.1
+++ src/libdar/tronconneuse.hpp	21 Mar 2005 21:11:33 -0000	1.3
@@ -52,11 +52,11 @@
 	//! tronconneuse is either read_only or write_only, read_write is not allowed.
 	//! The openning mode his mode is defined by encrupted_side's mode.
 	//! In write_only no skip() is allowed, writing is sequential from the beginning of the file to the end
 	//! (like writing to a pipe).
 	//! In read_only all skip() functions are available.
-	//! \ingroup Private
+	//! \ingroup Filters
     class tronconneuse : public generic_file
     {
     public:
 	    /// This is the constructor
 
Index: src/libdar/tuyau.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/tuyau.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/tuyau.hpp	18 Feb 2005 11:08:23 -0000	1.1.3.1
+++ src/libdar/tuyau.hpp	22 Mar 2005 16:13:38 -0000	1.3
@@ -41,11 +41,11 @@
 namespace libdar
 {
 
 	/// pipe implementation under the generic_file interface.
 
-	/// \ingroup Private
+	/// \ingroup Archive
 
     class tuyau : public generic_file, public thread_cancellation
     {
     public:
         tuyau(user_interaction & dialog, int fd); // fd is the filedescriptor of a pipe extremity
Index: src/libdar/wrapperlib.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/wrapperlib.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/wrapperlib.hpp	18 Feb 2005 11:08:22 -0000	1.1.3.1
+++ src/libdar/wrapperlib.hpp	21 Mar 2005 21:11:33 -0000	1.3
@@ -64,11 +64,11 @@
 
 	/// this class encapsulates calls to libz or libbz2
 
 	/// this is mainly an adaptation of libbz2 specificities to
 	/// have libb2 acting exactly as libz does.
-	/// \ingroup Private
+	/// \ingroup Filters
 
     class wrapperlib
     {
     public:
         wrapperlib(wrapperlib_mode mode);
Index: src/libdar/zapette.hpp
===================================================================
RCS file: /var/cvs/kaylix/dar/src/libdar/zapette.hpp,v
retrieving revision 1.1.3.1
retrieving revision 1.3
diff -U5 -r1.1.3.1 -r1.3
--- src/libdar/zapette.hpp	18 Feb 2005 11:08:27 -0000	1.1.3.1
+++ src/libdar/zapette.hpp	22 Mar 2005 16:13:38 -0000	1.3
@@ -46,11 +46,11 @@
 	/// zapette emulate a file that is remotely controlled by slave_zapette
 
 	/// class zapette sends order to slave_zapette throw a
 	/// a first pipe and receive informations or data in return
 	/// from a second pipe from slave_zapette
-	/// \ingroup Private
+	/// \ingroup Archive
     class zapette : public contextual
     {
     public:
 
 	    /// zapette constructor
@@ -86,11 +86,11 @@
 
 	/// this class answers to order given by a zapette object
 
 	/// through a pair of pipes slave_zapette return information about
 	/// a given local archive (single or multi slices).
-	/// \ingroup Private
+	/// \ingroup Archive
     class slave_zapette
     {
     public:
 
 	    /// slave_zapette constructor

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.6 (GNU/Linux)

iD8DBQBCQElPKiBWiPhIm90RAlJfAJ9CBO3L2a0Tiqr2RuH6A+Pc3no5DACfdHXt
+O3vSpdK/ErDhc/Jng+Nkbs=
=ADoH
-----END PGP SIGNATURE-----