[pygccxml-commit] source/pygccxml/docs definition.rest,1.2,1.3 pygccxml.rest,1.3,1.4

[Roman <rom...@us...>]

Update of /cvsroot/pygccxml/source/pygccxml/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11726/pygccxml/docs

Modified Files:
	definition.rest pygccxml.rest 
Log Message:
applying John Pallister <jo...@sy...> documentation changes.

Index: pygccxml.rest
===================================================================
RCS file: /cvsroot/pygccxml/source/pygccxml/docs/pygccxml.rest,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pygccxml.rest	31 Jan 2006 08:15:53 -0000	1.3
--- pygccxml.rest	5 Mar 2006 05:39:08 -0000	1.4
***************
*** 22,32 ****
  
  First of all let's see a small and simple `example`_. This example prints all 
! declarations found in `core_class_hierarchy.hpp`_ file. Also, for instances, that 
! describes C++ class, it will print bases and derived class names. This example 
! is also interesting because it `shows`_ us how it can be simple to find out all 
! bases and derived classes. If someone still is curious "how it can be in the real 
! life" he may look at `GCC-XML`_ `generated file`_.
  
! .. _`generated file` : ./core_class_hierarchy.hpp.xml
  .. _`core_class_hierarchy.hpp` : ./core_class_hierarchy.hpp
  .. _`shows` : ./example_output.txt
--- 22,32 ----
  
  First of all let's see a small and simple `example`_. This example prints all 
! declarations found in the `core_class_hierarchy.hpp`_ file. Also, for instances
! that describe a C++ class it will print base and derived class names. This example 
! is also interesting because it `shows`_ us how simple it is to find all base
! and derived classes. If someone is still curious how it looks "in the real 
! life" he may look at the `original XML file`_ generated by `GCC-XML`_.
  
! .. _`original XML file` : ./core_class_hierarchy.hpp.xml
  .. _`core_class_hierarchy.hpp` : ./core_class_hierarchy.hpp
  .. _`shows` : ./example_output.txt
***************
*** 36,51 ****
  -----------------------------------------
  
! Consider next situation: you have to parse the same set of files every day. 
! There are 2 possibilities to complete the task::
  
!   * Create header file that includes all files you need to parse
  
!   * Parse each file separately and then join the results
  
! The difference between these approaches is caching algorithm in second case. 
! `pygccxml`_ supports both of them. 
  
! That's not all. Do you familiar with `boost::type_traits`_ library? Well,
! `pygccxml`_ has some functionality offered by that library.
  
  -------
--- 36,51 ----
  -----------------------------------------
  
! Consider the following situation: you have to parse the same set of files every 
! day. There are 2 possibile ways to complete the task::
  
!   * create a header file that includes all files you need to parse
  
!   * parse each file separately and then join the results
  
! The difference between these approaches is the caching algorithm used in the 
! second case. `pygccxml`_ supports both of them. 
  
! That's not all. Do you familiar with the `boost::type_traits`_ library? Well,
! `pygccxml`_ includes some functionality offered by that library.
  
  -------
***************
*** 60,95 ****
  `UML diagram`_:
  
!  Look at this `UML diagram`_. All classes are defined by `pygccxml`_.declarations 
!  package. Defined classes are used to describe almost any C++ declaration. 
  
! Few words about convention. Every class name ends with "_t". The are several 
! reasons for it:
  
!  * I am used to C++ "std" convention. ( small letters with underscores )
   
!  * Most of the names are already exists in python and have the different meaning.
  
  Types hierarchy
  ---------------
  
! Types hierarchy is used to represent arbitrary type in C++. 
  
  Example 
  ~~~~~~~
  
! For variable "ptr"
          
      *const int\* ptr=0;*
          
! `pygccxml`_ will create next type
          
      *pointer_t( const_t( int_t() ) )*
      
! The ability to represent almost any type of C++ comes from "decorator" pattern. 
! That's not all! Do you aware of `boost::type_traits`_ library? `boost::type_traits`_
! library has been developed by John Maddock, Steve Cleary and others. `pygccxml`_ 
! reuse names proposed by this library. Also I took few ideas for testing 
! `pygccxml`_ type traits implementation. Here are some type traits implemented by 
! `pygccxml`_.
  
      + *base_type*
--- 60,96 ----
  `UML diagram`_:
  
!  Look at this `UML diagram`_. All the classes are defined by the 
!  `pygccxml`_.declarations package. Defined classes are used to describe almost 
!  any C++ declaration. 
  
! A few words about the naming convention used. Every class name ends with "_t". 
! The are several reasons for this:
  
!  * I am used to the C++ "std" convention, i.e. lower-case letters with underscores.
   
!  * Most of the names are already used in Python, and have a different meaning.
  
  Types hierarchy
  ---------------
  
! Types hierarchy is used to represent an arbitrary type in C++. 
  
  Example 
  ~~~~~~~
  
! For a variable "ptr"
          
      *const int\* ptr=0;*
          
! `pygccxml`_ will create the type
          
      *pointer_t( const_t( int_t() ) )*
      
! The ability to represent almost any type of C++ comes from the use of the 
! "decorator" pattern. That's not all! Are you aware of `boost::type_traits`_ 
! library? The `boost::type_traits`_ library has been developed by John Maddock, 
! Steve Cleary and others. `pygccxml`_ reuses the names proposed by this library. 
! Also I took few ideas for testing the `pygccxml`_ type traits implementation. 
! Here are some of the type traits implemented by `pygccxml`_.
  
      + *base_type*
***************
*** 156,166 ****
  ---------------------
  
! Declaration hierarchy is used to represent arbitrary C++ declaration. 
  
! *"declaration_t"* is a base class of declaration hierarchy. This class has few 
! properties. One of them is *"parent"* property. This property keeps reference to 
! scope declaration instance in which this declaration is defined. *"scopedef_t"*
! class derives from *"declaration_t"*. This class is used to say - "I may have 
! other declarations inside". The pattern that is used here is "composite".
  
  ------
--- 157,168 ----
  ---------------------
  
! A declaration hierarchy is used to represent an arbitrary C++ declaration. 
  
! *"declaration_t"* is the base class of the declaration hierarchy. This class has 
! a few properties. One of them is the *"parent"* property. This property keeps a 
! reference to the scope declaration instance in which this declaration is defined. 
! The *"scopedef_t"* class derives from *"declaration_t"*. This class is used to 
! say - "I may have other declarations inside". The "composite" design pattern is 
! used here.
  
  ------
***************
*** 171,180 ****
  --------
  
! `Parser package`_ ( "`pygccxml`_.parser" ). This is the heart of `pygccxml`_ project.
! Classes in this package implements parsing and binding functionality. There are 
! 3 classes and 2 functions that user should know about:
  
! + *config_t* - class that accumulates all settings of `GCC-XML`_ and `pygccxml`_.
!   User can work with relative files paths. In this case files are searched in next order:
    
    1. current directory
--- 173,183 ----
  --------
  
! `Parser package`_ ( "`pygccxml`_.parser" ). This is the heart of the `pygccxml`_ 
! project. Classes in this package implement parsing and binding functionality. 
! There are 3 classes and 2 functions that user should know about:
  
! + *config_t* - a class that accumulates all the settings of `GCC-XML`_ and 
!   `pygccxml`_. Users can work with relative files paths. In this case files are 
!   searched in the following order:
    
    1. current directory
***************
*** 185,202 ****
  
  + *source_reader_t* - the only class that works with `GCC-XML`_. This class has
!   only one responsibility: to convert source file declarations and types to
!   `pygccxml`_ objects model. You can think about this class as `GCC-XML`_ generated
!   file reader only.
    
! + *project_reader_t* - think about this class as a linker or a binder. Explanation:
!   usually you will define base class in one header file and derived in an other one.
!   After running *source_reader_t* on base header and on derived header you will
!   get 2 definitions of base class. More then one of the definitions will not
!   contain information about derived classes. *project_reader_t* was born to solve
!   this situation. It implements few algorithms to solve that problem and other
!   similar ones. Right now it implements next algorithms:
  
    1. namespace joining.
!   2. join class hierarchies
    3. rebinding types to new class hierarchies
    4. linking overloaded functions
--- 188,206 ----
  
  + *source_reader_t* - the only class that works with `GCC-XML`_. This class has
!   only one responsibility: to convert source file declarations and types into the
!   `pygccxml`_ object model. You can think about this class as simply a reader for 
!   `GCC-XML`_-generated files.
    
! + *project_reader_t* - think of this class as a linker or a binder. Explanation:
!   usually you will define a base class in one header file and a derived class in 
!   another. After running *source_reader_t* on the base class header file and on 
!   the derived class header file you will have two definitions of the base class. 
!   All but one of the definitions will not contain information about the derived 
!   classes. *project_reader_t* was born to solve this situation. It implements 
!   several algorithms to solve that problem and other similar ones. Right now it 
!   implements these algorithms:
  
    1. namespace joining.
!   2. joining class hierarchies
    3. rebinding types to new class hierarchies
    4. linking overloaded functions
***************
*** 204,220 ****
    There are 2 ways to solve the problem:
  
!   1. To compile every file and than to run the algorithms.
!      In order to run this mode set *compilation_mode* ( in instance of *config_t* )
!      to *COMPILATION_MODE.FILE_BY_FILE*. 
  
!   2. To create a temporal header file, that will include all headers you want to 
!      compile. In order to run this mode set *compilation_mode* ( in instance of 
!      *config_t* ) to *COMPILATION_MODE.ALL_AT_ONCE*. In other words, in this 
!      mode *project_reader_t* acts like *source_reader_t*, no difference.
  
!   Two modes, why?! The answer is simple - cache. You don't want to pay for 
!   compilation and processing result for files that has not been changed, right? 
!   *COMPILATION_MODE.FILE_BY_FILE* gives you the possibility to use cache! For 
!   further explanation please see `Parser package`_ design.
  
  Interface description 
--- 208,223 ----
    There are 2 ways to solve the problem:
  
!   1. Compile every file to run the algorithms. In order to select this mode 
!      set *compilation_mode* (in the instance of *config_t*) to *COMPILATION_MODE.FILE_BY_FILE*. 
  
!   2. Create a temporary header file, that will include all headers you want to 
!      compile. In order to select this mode set *compilation_mode* (in the instance 
!      of *config_t* ) to *COMPILATION_MODE.ALL_AT_ONCE*. In other words, in this 
!      mode *project_reader_t* acts like *source_reader_t*, there's no difference.
  
!   Two modes, why?! The answer is simple - the cache. You don't want to pay for 
!   compilation and processing results for files that have not changed, right? 
!   *COMPILATION_MODE.FILE_BY_FILE* gives you the possibility to use the cache! 
!   For further explanation please see `Parser package`_ design.
  
  Interface description 
***************
*** 229,256 ****
  
  + *read_string(self, content)* - small convenience function. The *content* 
!   should be valid C++ code. This function will return top level namespaces's list.
  
  + *source_reader_t.read_file(self, source_file)* This function will return
!   top level namespaces list.
  
! + *project_reader_t.read_files(self, files)* This function will return
!   top level namespaces list. *files* - list of files to be compiled. 
!   This list may contain a file name ( string ) or instance of class 
!   *file_configuration_t*. In case the item is an instance of class *file_configuration_t* 
!   then file will be compiled and parsed using it's configuration. Project 
!   configuration stays unchanged.  
  
  + *source_reader_t.create_xml_file(self, source_file, destination_file_path=None)* 
!   This function will return file name of the file, created by `GCC-XML`_. If
    *destination_file_path* is not *None* then this file path will be used and 
    returned.
  
! + *source_reader_t.read_xml_file(self, xmlfile)* This function will return top 
!   level namespaces list.
     
    Right now top level namespaces are: "::" and "std".
  
!   Main purpose of *source_reader_t.create_xml_file* and *source_reader_t.read_xml_file*
!   is to make an easy cross-platform development. 
    
  *pygccxml.parser*
--- 232,260 ----
  
  + *read_string(self, content)* - small convenience function. The *content* 
!   should be valid C++ code. This function will return the list of top level 
!   namespaces.
  
  + *source_reader_t.read_file(self, source_file)* This function will return
!   the list of top level namespaces.
  
! + *project_reader_t.read_files(self, files)* This function will return the top 
!   level namespaces list. *files* - list of files to be compiled. This list may 
!   contain a file name ( string ) or instance of class *file_configuration_t*. 
!   If the item is an instance of class *file_configuration_t* then the file will 
!   be compiled and parsed using its configuration. The project configuration stays 
!   unchanged.  
  
  + *source_reader_t.create_xml_file(self, source_file, destination_file_path=None)* 
!   This function will return the file name of the file, created by `GCC-XML`_. If
    *destination_file_path* is not *None* then this file path will be used and 
    returned.
  
! + *source_reader_t.read_xml_file(self, xmlfile)* This function will return the 
!   top level namespaces list.
     
    Right now top level namespaces are: "::" and "std".
  
!   The main purpose of *source_reader_t.create_xml_file* and *source_reader_t.read_xml_file*
!   is to ease cross-platform development. 
    
  *pygccxml.parser*
***************
*** 270,280 ****
  There are 2 private classes in this package:
  
!   1. *scanner_t* - this class scans "XML" file, generated by `GCC-XML`_ and creates
!      `pygccxml`_ declarations and types classes. After the xml file has been processed
!      declarations and types class instances keeps references to each other using
!      `GCC-XML`_ generated id's.
  
    2. *linker_t* - this class contains logic for replacing `GCC-XML`_ generated 
!      ids with references to declarations\\types class instances.
  
  
--- 274,284 ----
  There are 2 private classes in this package:
  
!   1. *scanner_t* - this class scans the "XML" file, generated by `GCC-XML`_ and 
!      creates `pygccxml`_ declarations and types classes. After the xml file has 
!      been processed declarations and type class instances keeps references to 
!      each other using `GCC-XML`_ generated id's.
  
    2. *linker_t* - this class contains logic for replacing `GCC-XML`_ generated 
!      ids with references to declarations or type class instances.
  
  
***************
*** 283,290 ****
  -----------------
  
! `pygccxml`_ comes with comprehensive unit tests. It is running on windows xp and 
! `Debian Linux`_. I am using `Python`_ 2.3 and `GCC-XML`_ 0.6.0. Right now I am running
! more then 75 tests. They test almost every piece of code. Also I have performance tests.
! Most of the time I am using "white box" testing strategy.
  
  ---------    
--- 287,295 ----
  -----------------
  
! `pygccxml`_ comes with comprehensive unit tests. It is running on Windows XP and 
! `Debian Linux`_. I am using `Python`_ [ 2.3 | 2.4 ] and `GCC-XML`_ [ 0.6.0 | CVS ].
! Right now I am running more then 100 tests. They test almost every piece of code. 
! Also I have performance tests. Most of the time I am using "white box" testing 
! strategy.
  
  ---------    
***************
*** 292,296 ****
  ---------
  
! * My wife Yulia - she helped me to edit initial version of this manuals. All 
    mistakes and bugs are mine. I'd like to believe that I know `Python`_ better 
    then English.
--- 297,301 ----
  ---------
  
! * My wife Yulia - she helped me to edit the initial version of this manuals. All 
    mistakes and bugs are mine. I'd like to believe that I know `Python`_ better 
    then English.
***************
*** 298,302 ****
  * Brad King for `GCC-XML`_
  
! * Detlev Offenbach for `Eric 3.4`_
  
  * `Docutils`_ - easy to use documentation system
--- 303,307 ----
  * Brad King for `GCC-XML`_
  
! * Detlev Offenbach for `Eric 3.6`_
  
  * `Docutils`_ - easy to use documentation system
***************
*** 305,308 ****
--- 310,315 ----
    `SourceForge`_
  
+ * John Pallister <jo...@sy...> - he helped me to edit\\correct documentation
+ 
  * Hosted by |SourceForge|__
  

Index: definition.rest
===================================================================
RCS file: /cvsroot/pygccxml/source/pygccxml/docs/definition.rest,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** definition.rest	16 Jan 2006 05:59:44 -0000	1.2
--- definition.rest	5 Mar 2006 05:39:08 -0000	1.3
***************
*** 6,10 ****
  -- Introduction to `GCC-XML`_                                                    
                                                                                   
! The purpose of `pygccxml`_ is to read a generated file and provide simple        
  framework to navigate C++ declarations using Python classes.                     
  
--- 6,10 ----
  -- Introduction to `GCC-XML`_                                                    
                                                                                   
! The purpose of `pygccxml`_ is to read a generated file and provide a simple        
  framework to navigate C++ declarations using Python classes.