------------------------
PCE2 
C++ Documentation Engine
------------------------


Introduction
--
PCE2 is a powerful, modular documentation engine for C++. By processing
a series of C++ header files (.h or .hh) it removes specially marked
comments and generates a tree data structure representing the classes,
namespaces, and other primitives found within the set of files. This 
data structure is made available to end-user "plugins" which walk the
tree and generate whatever output is required.

Using PCE2
--
PCE2 is incapable of generating any output by itself. It requires at
least one plugin which will walk the generated tree of the header
files. In particular, the first plugin must be named "output.plg" and
have a "plugin" subroutine. PCE2 loads this plugin and calls the subroutine,
passing the base of the header tree as the first argument.


Data structures in PCE2
--
The primary data structure is a recursive type named Object. A parse
tree composed of "Object"s is passed to the output plugin once all
header files have been parsed. The output plugin then walks the various
methods and properties of Object to generate output. 

Additionally, there are a few subclasses of the Object type. At this
time the only one of note is the Function type. This sub-type provides
additional information on the return type, const-specifiers and other
function modifiers available in C++.

Definitions
--

item                    - refers to any thing from classes to friends
class(es)               - refers to classes and structs
space(es)               - refers to all C++ types which may hold a class
                          including: namespace, class or union


Object::
Basic Properties
--------------------------------------
Object::{name}          - object name w/o path (use Object::name())
Object::{fullname}      - object name including path (use Object::fullname())
Object::{htmlname}      - object name rendered in HTML
Object::{comments}      - ??
Object::{space}         - namespace/class/struct in which this object resides
Object::{ntype}         - object type ID (use Object::type_name())
			  1 = Namespace
			  2 = Class
			  3 = Struct
			  4 = Union
			  5 = Function
			  6 = Variable
			  7 = Typedef
			  8 = Friend
			  9 = Macro
Object::{access}	- object access ID (use Object::access_name())
			  1 = Public
			  2 = Protected
			  3 = Private
Object::{file}		- file in which this object resides
Object::{short}		- summary comment for this object (designated by //:)
Object::{long}		- extended comment for this object (designated by //-)
Object::{unique_string} - Unique Variables ("name=value") (designated by //! )


Object::
Basic Accessor Methods
--------------------------------------
Object::name()          - name of item w/o path
Object::fullname()      - name of item including path
Object::type_name()     - string describing type of this item
Object::access_name()   - string describing access of this item
Object::href()          - returns a relative hyperlink to the file which
			  contains this object
Object::full_href()     - returns an absolute hyperlink to the file which
			  contains this object
Object::is_known()      - true if object was encountered in source; false
		          if pce2 assumed its existence from class definitions
			  or calls
Object::is_namespace()  - true if this object type is a namespace

Object::is_class()
Object::is_union()
Object::is_function()
Object::is_typedef()
Object::is_friend()
Object::is_template()


Object::
List Accessor Methods
--------------------------------------
These methods return a list of sub-objects within an object. 
Use these to extract subsets of the items in a space.

Object::children()      - all classes derived from this class
Object::parents()       - immediate base classes of this class
Object::known_parents() - same as Object::parents() with the additional
                          constraint that all object must satisfy "is_known()"

Object::all()           - all items in all subtrees (recursive) 
Object::items()		- items in this space
Object::spaces()	- classes and namespaces in this space
Object::classes()	- classes in this space
Object::unions()	- unions in this space
Object::namespaces()	- namespaces in this space
Object::friends()	- friends in this space
Object::typedefs()	- typedefs in this space
Object::macros()	- macros in this space

Object::public()	- public items in this space
Object::private()	- private  items in this space
Object::protected()	- protected items in this space

Object::get_by_type(type)     - uses type index number; returns a list of
			        sub-objects filtered by type (see Object::ntype)
Object::get_by_access(access) - uses access index number; returns a list of
			        sub-objects filtered by access
 


Function:: (sub-class of Object)
Basic Properties
--------------------------------------
Function::{type}        - return type of this function
Function::{args}        - unparsed string of this function's argument list
Function::{html_type}   - html rendering of the return type
Function::{html_args}   - html rendering of the function argument list

Function::{const}       - returns true if this is a const function
Function::{explicit}    - returns true if this is an explicit ctor
Function::{virtual}     - returns true if this is a virtual method
Function::{static}      - returns true if this a static method



Additional notes
----------------------------

The variable "$file_global_string" contains a global string which is created
by using:
//: A message 1
//: on 2 lines
//! Global=message_1
//: A message 2
//! Global=message_2
So that $file_global_string =
! message_1
: A message 1
: on 2 lines
! message_2
: A message 2

It is up to the plugins to decide how to use the information

Sorters
--
Sorters are mini functions used to sort lists

Ex.  @list= sort byname $obj->get_public();

  byname  - sorts by name


Perl Notes
--

$obj->{foo} is equivelent to $$obj{foo}
$obj->foo() is equivelent to foo($obj) 

$_ is local scope in nature and thus can be used one inside another.

  foreach ($object->spaces()) {
    print "start $$_{name};\n";  # prints space name
    foreach ($_->functions()) {
      print "$$_{name}\n";       # prints functions in space
    }
    print "end $$_{name};\n\n";  # prints space name
  }
      
Often doing a "perl myplugin.plg" will turn up errors not caught 
otherwise in perl.  Plugins use an eval which does not check
as carefully as one would like.






