90 The first block is
for Copyright issues. You clearly show that
this file is
91 distributed under the terms of the GPL ; that it comes with no warranty and
92 that you are the copyright holder of the file. The Copyright line has to show
93 all the years
this file has been worked on. Several persons may hold
94 the copyright of a file. In
this case, put one Copyright line per person.
95 The $Id: line is
for the CVS system. It will put useful information on
this
96 line when the file will be committed, indicating who last modified
this file,
97 when, and which version number it is.
99 The second block is
for referencing
this file into Doxygen
's documentation
100 system. It's quite
explicit and MANDATORY
if you want to document the classes
103 \subsection classlev Documenting at
class level
104 Each class must have a little documentation block explaining what it does.
105 Moreover, you can't document a class member if the class itself isn't
106 documented. Just put a Doxygen block before your class and explain what it is
118 class my_very_cool_class
124 Don
't hesitate to use Doxygen's special tags, like \\note or \\bug.
126 \subsection memblev Documenting at member level
127 Once your
class is briefly described, you can start the "true" documenting, that
128 is, clearly and precisely describe your public interface. Once again, everything
129 is better explained in Doxygen's own documentation, but here is an example for
141 float sqrt (
float a_number);
146 Once you have done
this, and rebuild the documentation, your
class will appear in
147 the Class Hierarchy diagram, with it's own documentation page and automatically
148 generated Inheritance Diagram. Have a look at the \link
image Image Class Page
149 \endlink for a sample of the result you can expect, and \link
image.h the
image.h
150 file \endlink (see the source code) to see how it has been done.
152 \section names Method naming
153 \subsection namgen General naming conventions
154 There are several different more or less popular ways to name your functions and
155 classes. Depending on what you like, you can call the same function
156 perform_something () or PerformSomething (), etc... To keep the interface as clear
157 and homogeneous as possible, here are a few rules to follow when naming your classes
160 \li Use lower cases, and '_' as a separator if your function name has several words
161 (ex: perform_something ()).
163 \li Member access functions should be as short as possible. For read-access, use the
164 most direct name possible (i.e. length () for the length of an object), for write
165 access, use set_member style names (set_length (u_int16 l)). Of course, the member
166 itself should then have a different name than length. Placing an underscore right
167 after (length_) for naming your member is widely used through the code - but you
168 are free to do something else if you don't like it.
170 \li Methods returning something more complicated than a simple %data type (i.e.
171 functions that returns a pointer to a complex %data structure, etc...) should
172 use a get_name style instead. For example, a method returning an %
image of an
175 \li If your class is static, the "manual" constructor/destructor should then be named
176 respectively init () and cleanup ().
178 Let's see a concrete example of this naming convention through a class interface:
209 vector <image> frame;
213 \subsection namcons Constructor selection
for Python
214 As Python can only have one constructor per
class, you have to choose
215 which one will be available.
216 The
default constructor often makes sense ; but
if your
class requires a
217 constructor with arguments, then you can transgress this rule of course.
218 In any case, be aware that you need to be able to reach the state of ANY
219 of your C++ constructors from Python by using the available constructor
220 plus one or more of your class methods.
221 To select which constructor is available, embed the others with a ifndef SWIG
244 \subsection nampy Making overloaded methods and operators available
for Python
245 SWIG doesn
't like overloaded functions and operators, and will print a warning
246 if it meets one. But the functions or operators you have overloaded have to be
247 available from the Python interface. To make them available, you should us a
248 ifdef SWIG directive to declare another inlined function that matches the overloaded
249 function or operator. An example is better than a long explanation:
259 void draw (int x, int y);
266 void draw (int x, int y, int l, int h);
271 void draw_part (int x, int y, int l, int h)
282 myclass& operator = (const myclass & src);
289 void copy (const myclass& src)
298 Don't forget to comment your methods accordingly to their access.
300 Functions synonym to Operators should have
explicit names. As an
operator
301 could have several meanings (+ could be said
"add" or
"concat",
for
302 example) you are free to choose whatever name fits best with your usage.
304 \section args Argument passing conventions
306 \subsection objcts Object passing
307 Most often you will work with %
objects created by yourself or someone
else.
308 Passing such %
objects to methods by value has to be absolutely avoided,
for
309 performances and bug issues. Passing a big
object by value to a
function
310 requires memory to be allocated
for the
function's object, and of course the
311 copy-constructor and destructor to be called. Needless to say, that without
312 a copy-constructor most complicated %objects won't be correctly passed, and
313 this is a source of useless bug tracking.
315 Instead of passing your %
objects by value, you
'll pass them by reference.
316 That way, no memory is allocated, and actions are performed directly on your
317 object. To make it obvious which methods modify the object you're passing
318 and which don
't, the following conventions has been set up:
319 \li When a function requires an object and doesn't modify it, pass it by
322 void doesntmodify (
const myclass & myobject);
325 \li When a
function requires an
object and modifies it, pass it by address.
327 void modify (myclass * myobject);
330 \note Of course,
this doesn
't apply to your operator overloading functions
331 which are obviously explicit.
333 And, to make sure nobody will ever pass one of your %objects by value,
334 declare the copy-constructor as private:
342 myclass (myclass & src);
345 This will cause a compilation error if someone ever tries to pass an object
346 of your class by value.
u_int16 length() const
Returns the length of the drawable.
#define u_int16
16 bits long unsigned integer
Image manipulation class.
u_int16 height() const
Returns the height of the drawable.
animation()
Default constructor.
The global container for access to all the different game objects from within a script.
Class that handles animated elements, their update and their playback.
image * get_image(u_int16 nbr)
Returns a pointer to a desired image.