| 1 |
------------------------ |
| 2 |
PCE2 |
| 3 |
C++ Documentation Engine |
| 4 |
------------------------ |
| 5 |
|
| 6 |
|
| 7 |
Introduction |
| 8 |
-- |
| 9 |
PCE2 is a powerful, modular documentation engine for C++. By processing |
| 10 |
a series of C++ header files (.h or .hh) it removes specially marked |
| 11 |
comments and generates a tree data structure representing the classes, |
| 12 |
namespaces, and other primitives found within the set of files. This |
| 13 |
data structure is made available to end-user "plugins" which walk the |
| 14 |
tree and generate whatever output is required. |
| 15 |
|
| 16 |
Using PCE2 |
| 17 |
-- |
| 18 |
PCE2 is incapable of generating any output by itself. It requires at |
| 19 |
least one plugin which will walk the generated tree of the header |
| 20 |
files. In particular, the first plugin must be named "output.plg" and |
| 21 |
have a "plugin" subroutine. PCE2 loads this plugin and calls the subroutine, |
| 22 |
passing the base of the header tree as the first argument. |
| 23 |
|
| 24 |
|
| 25 |
Data structures in PCE2 |
| 26 |
-- |
| 27 |
The primary data structure is a recursive type named Object. A parse |
| 28 |
tree composed of "Object"s is passed to the output plugin once all |
| 29 |
header files have been parsed. The output plugin then walks the various |
| 30 |
methods and properties of Object to generate output. |
| 31 |
|
| 32 |
Additionally, there are a few subclasses of the Object type. At this |
| 33 |
time the only one of note is the Function type. This sub-type provides |
| 34 |
additional information on the return type, const-specifiers and other |
| 35 |
function modifiers available in C++. |
| 36 |
|
| 37 |
Definitions |
| 38 |
-- |
| 39 |
|
| 40 |
item - refers to any thing from classes to friends |
| 41 |
class(es) - refers to classes and structs |
| 42 |
space(es) - refers to all C++ types which may hold a class |
| 43 |
including: namespace, class or union |
| 44 |
|
| 45 |
|
| 46 |
Object:: |
| 47 |
Basic Properties |
| 48 |
-------------------------------------- |
| 49 |
Object::{name} - object name w/o path (use Object::name()) |
| 50 |
Object::{fullname} - object name including path (use Object::fullname()) |
| 51 |
Object::{htmlname} - object name rendered in HTML |
| 52 |
Object::{comments} - ?? |
| 53 |
Object::{space} - namespace/class/struct in which this object resides |
| 54 |
Object::{ntype} - object type ID (use Object::type_name()) |
| 55 |
1 = Namespace |
| 56 |
2 = Class |
| 57 |
3 = Struct |
| 58 |
4 = Union |
| 59 |
5 = Function |
| 60 |
6 = Variable |
| 61 |
7 = Typedef |
| 62 |
8 = Friend |
| 63 |
9 = Macro |
| 64 |
Object::{access} - object access ID (use Object::access_name()) |
| 65 |
1 = Public |
| 66 |
2 = Protected |
| 67 |
3 = Private |
| 68 |
Object::{file} - file in which this object resides |
| 69 |
Object::{short} - summary comment for this object (designated by //:) |
| 70 |
Object::{long} - extended comment for this object (designated by //-) |
| 71 |
Object::{unique_string} - Unique Variables ("name=value") (designated by //! ) |
| 72 |
|
| 73 |
|
| 74 |
Object:: |
| 75 |
Basic Accessor Methods |
| 76 |
-------------------------------------- |
| 77 |
Object::name() - name of item w/o path |
| 78 |
Object::fullname() - name of item including path |
| 79 |
Object::type_name() - string describing type of this item |
| 80 |
Object::access_name() - string describing access of this item |
| 81 |
Object::href() - returns a relative hyperlink to the file which |
| 82 |
contains this object |
| 83 |
Object::full_href() - returns an absolute hyperlink to the file which |
| 84 |
contains this object |
| 85 |
Object::is_known() - true if object was encountered in source; false |
| 86 |
if pce2 assumed its existence from class definitions |
| 87 |
or calls |
| 88 |
Object::is_namespace() - true if this object type is a namespace |
| 89 |
|
| 90 |
Object::is_class() |
| 91 |
Object::is_union() |
| 92 |
Object::is_function() |
| 93 |
Object::is_typedef() |
| 94 |
Object::is_friend() |
| 95 |
Object::is_template() |
| 96 |
|
| 97 |
|
| 98 |
Object:: |
| 99 |
List Accessor Methods |
| 100 |
-------------------------------------- |
| 101 |
These methods return a list of sub-objects within an object. |
| 102 |
Use these to extract subsets of the items in a space. |
| 103 |
|
| 104 |
Object::children() - all classes derived from this class |
| 105 |
Object::parents() - immediate base classes of this class |
| 106 |
Object::known_parents() - same as Object::parents() with the additional |
| 107 |
constraint that all object must satisfy "is_known()" |
| 108 |
|
| 109 |
Object::all() - all items in all subtrees (recursive) |
| 110 |
Object::items() - items in this space |
| 111 |
Object::spaces() - classes and namespaces in this space |
| 112 |
Object::classes() - classes in this space |
| 113 |
Object::unions() - unions in this space |
| 114 |
Object::namespaces() - namespaces in this space |
| 115 |
Object::friends() - friends in this space |
| 116 |
Object::typedefs() - typedefs in this space |
| 117 |
Object::macros() - macros in this space |
| 118 |
|
| 119 |
Object::public() - public items in this space |
| 120 |
Object::private() - private items in this space |
| 121 |
Object::protected() - protected items in this space |
| 122 |
|
| 123 |
Object::get_by_type(type) - uses type index number; returns a list of |
| 124 |
sub-objects filtered by type (see Object::ntype) |
| 125 |
Object::get_by_access(access) - uses access index number; returns a list of |
| 126 |
sub-objects filtered by access |
| 127 |
|
| 128 |
|
| 129 |
|
| 130 |
Function:: (sub-class of Object) |
| 131 |
Basic Properties |
| 132 |
-------------------------------------- |
| 133 |
Function::{type} - return type of this function |
| 134 |
Function::{args} - unparsed string of this function's argument list |
| 135 |
Function::{html_type} - html rendering of the return type |
| 136 |
Function::{html_args} - html rendering of the function argument list |
| 137 |
|
| 138 |
Function::{const} - returns true if this is a const function |
| 139 |
Function::{explicit} - returns true if this is an explicit ctor |
| 140 |
Function::{virtual} - returns true if this is a virtual method |
| 141 |
Function::{static} - returns true if this a static method |
| 142 |
|
| 143 |
|
| 144 |
|
| 145 |
Additional notes |
| 146 |
---------------------------- |
| 147 |
|
| 148 |
The variable "$file_global_string" contains a global string which is created |
| 149 |
by using: |
| 150 |
//: A message 1 |
| 151 |
//: on 2 lines |
| 152 |
//! Global=message_1 |
| 153 |
//: A message 2 |
| 154 |
//! Global=message_2 |
| 155 |
So that $file_global_string = |
| 156 |
! message_1 |
| 157 |
: A message 1 |
| 158 |
: on 2 lines |
| 159 |
! message_2 |
| 160 |
: A message 2 |
| 161 |
|
| 162 |
It is up to the plugins to decide how to use the information |
| 163 |
|
| 164 |
Sorters |
| 165 |
-- |
| 166 |
Sorters are mini functions used to sort lists |
| 167 |
|
| 168 |
Ex. @list= sort byname $obj->get_public(); |
| 169 |
|
| 170 |
byname - sorts by name |
| 171 |
|
| 172 |
|
| 173 |
Perl Notes |
| 174 |
-- |
| 175 |
|
| 176 |
$obj->{foo} is equivelent to $$obj{foo} |
| 177 |
$obj->foo() is equivelent to foo($obj) |
| 178 |
|
| 179 |
$_ is local scope in nature and thus can be used one inside another. |
| 180 |
|
| 181 |
foreach ($object->spaces()) { |
| 182 |
print "start $$_{name};\n"; # prints space name |
| 183 |
foreach ($_->functions()) { |
| 184 |
print "$$_{name}\n"; # prints functions in space |
| 185 |
} |
| 186 |
print "end $$_{name};\n\n"; # prints space name |
| 187 |
} |
| 188 |
|
| 189 |
Often doing a "perl myplugin.plg" will turn up errors not caught |
| 190 |
otherwise in perl. Plugins use an eval which does not check |
| 191 |
as carefully as one would like. |
| 192 |
|
| 193 |
|
| 194 |
|
| 195 |
|
| 196 |
|
| 197 |
|