Debian Codegraph @

Documentation/Reference/pce2.txt

raw
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