00001
00002
00003
00004
00005
00006
00007
00008
00009
00010
00011
00012
00013
00014
00015
00016
00017
00018
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
00058
00059
00060
00061
00062
00063
00064
00065
00066
00067
00068
00069
00070
00071
00072
00073
00074
00075
00076
00077
00078
00079
00080
00081
00082
00083
00084
00085
00086
00087
00088 \endverbatim
00089
00090 The first block is for Copyright issues. You clearly show that this file is
00091 distributed under the terms of the GPL ; that it comes with no warranty and
00092 that you are the copyright holder of the file. The Copyright line has to show
00093 all the years this file has been worked on. Several persons may hold
00094 the copyright of a file. In this case, put one Copyright line per person.
00095 The $Id: line is for the CVS system. It will put useful information on this
00096 line when the file will be committed, indicating who last modified this file,
00097 when, and which version number it is.
00098
00099 The second block is for referencing this file into Doxygen's documentation
00100 system. It's quite explicit and MANDATORY if you want to document the classes
00101 in this file.
00102
00103 \subsection classlev Documenting at class level
00104 Each class must have a little documentation block explaining what it does.
00105 Moreover, you can't document a class member if the class itself isn't
00106 documented. Just put a Doxygen block before your class and explain what it is
00107 for:
00108
00109 \verbatim
00110
00111
00112
00113
00114
00115
00116
00117
00118 class my_very_cool_class
00119 {
00120 .....
00121 }
00122 \endverbatim
00123
00124 Don't hesitate to use Doxygen's special tags, like \\note or \\bug.
00125
00126 \subsection memblev Documenting at member level
00127 Once your class is briefly described, you can start the "true" documenting, that
00128 is, clearly and precisely describe your public interface. Once again, everything
00129 is better explained in Doxygen's own documentation, but here is an example for
00130 a member function:
00131
00132 \verbatim
00133 class my_class
00134 {
00135 public:
00136
00137
00138
00139
00140
00141 float sqrt (float a_number);
00142 }
00143
00144 \endverbatim
00145
00146 Once you have done this, and rebuild the documentation, your class will appear in
00147 the Class Hierarchy diagram, with it's own documentation page and automatically
00148 generated Inheritance Diagram. Have a look at the \link image Image Class Page
00149 \endlink for a sample of the result you can expect, and \link image.h the image.h
00150 file \endlink (see the source code) to see how it has been done.
00151
00152 \section names Method naming
00153 \subsection namgen General naming conventions
00154 There are several different more or less popular ways to name your functions and
00155 classes. Depending on what you like, you can call the same function
00156 perform_something () or PerformSomething (), etc... To keep the interface as clear
00157 and homogeneous as possible, here are a few rules to follow when naming your classes
00158 and functions:
00159
00160 \li Use lower cases, and '_' as a separator if your function name has several words
00161 (ex: perform_something ()).
00162
00163 \li Member access functions should be as short as possible. For read-access, use the
00164 most direct name possible (i.e. length () for the length of an object), for write
00165 access, use set_member style names (set_length (u_int16 l)). Of course, the member
00166 itself should then have a different name than length. Placing an underscore right
00167 after (length_) for naming your member is widely used through the code - but you
00168 are free to do something else if you don't like it.
00169
00170 \li Methods returning something more complicated than a simple %data type (i.e.
00171 functions that returns a pointer to a complex %data structure, etc...) should
00172 use a get_name style instead. For example, a method returning an %image of an
00173 %animation should be named get_image ().
00174
00175 \li If your class is static, the "manual" constructor/destructor should then be named
00176 respectively init () and cleanup ().
00177
00178 Let's see a concrete example of this naming convention through a class interface:
00179 \verbatim
00180 class animation
00181 {
00182 public:
00183
00184 animation ();
00185
00186
00187 ~animation ();
00188
00189 u_int16 length ()
00190 {
00191 return length_;
00192 }
00193
00194 u_int16 height ()
00195 {
00196 return height_;
00197 }
00198
00199 image * get_image (u_int16 pos)
00200 {
00201 return frame[pos];
00202 }
00203
00204 .....
00205
00206 private:
00207 u_int16 length_;
00208 u_int16 height_;
00209 vector <image> frame;
00210 }
00211 \endverbatim
00212
00213 \subsection namcons Constructor selection for Python
00214 As Python can only have one constructor per class, you have to choose
00215 which one will be available.
00216 The default constructor often makes sense ; but if your class requires a
00217 constructor with arguments, then you can transgress this rule of course.
00218 In any case, be aware that you need to be able to reach the state of ANY
00219 of your C++ constructors from Python by using the available constructor
00220 plus one or more of your class methods.
00221 To select which constructor is available, embed the others with a ifndef SWIG
00222 directive.
00223 \verbatim
00224 class image
00225 {
00226 public:
00227
00228 image ();
00229
00230 #ifndef SWIG
00231
00232 image (u_int16 l, u_int16 h);
00233 #endif
00234
00235
00236
00237
00238 void resize (u_int16 l, u_int16 h);
00239 ...
00240 };
00241 \endverbatim
00242
00243
00244 \subsection nampy Making overloaded methods and operators available for Python
00245 SWIG doesn't like overloaded functions and operators, and will print a warning
00246 if it meets one. But the functions or operators you have overloaded have to be
00247 available from the Python interface. To make them available, you should us a
00248 ifdef SWIG directive to declare another inlined function that matches the overloaded
00249 function or operator. An example is better than a long explanation:
00250 \verbatim
00251 class myclass
00252 {
00253 public:
00254
00255 ......
00256
00257
00258
00259 void draw (int x, int y);
00260 #ifndef SWIG
00261
00262
00263
00264
00265
00266 void draw (int x, int y, int l, int h);
00267 #endif
00268
00269
00270
00271 void draw_part (int x, int y, int l, int h)
00272 {
00273 draw (x, y, l, h);
00274 }
00275
00276
00277
00278
00279
00280
00281
00282 myclass& operator = (const myclass & src);
00283
00284
00285
00286
00287
00288
00289 void copy (const myclass& src)
00290 {
00291 *this = src;
00292 }
00293 ...
00294
00295 }
00296 \endverbatim
00297
00298 Don't forget to comment your methods accordingly to their access.
00299
00300 Functions synonym to Operators should have explicit names. As an operator
00301 could have several meanings (+ could be said "add" or "concat", for
00302 example) you are free to choose whatever name fits best with your usage.
00303
00304 \section args Argument passing conventions
00305
00306 \subsection objcts Object passing
00307 Most often you will work with %objects created by yourself or someone else.
00308 Passing such %objects to methods by value has to be absolutely avoided, for
00309 performances and bug issues. Passing a big object by value to a function
00310 requires memory to be allocated for the function's object, and of course the
00311 copy-constructor and destructor to be called. Needless to say, that without
00312 a copy-constructor most complicated %objects won't be correctly passed, and
00313 this is a source of useless bug tracking.
00314
00315 Instead of passing your %objects by value, you'll pass them by reference.
00316 That way, no memory is allocated, and actions are performed directly on your
00317 object. To make it obvious which methods modify the object you're passing
00318 and which don't, the following conventions has been set up:
00319 \li When a function requires an object and doesn't modify it, pass it by
00320 const reference.
00321 \code
00322 void doesntmodify (const myclass & myobject);
00323 \endcode
00324
00325 \li When a function requires an object and modifies it, pass it by address.
00326 \code
00327 void modify (myclass * myobject);
00328 \endcode
00329
00330 \note Of course, this doesn't apply to your operator overloading functions
00331 which are obviously explicit.
00332
00333 And, to make sure nobody will ever pass one of your %objects by value,
00334 declare the copy-constructor as private:
00335 \code
00336 class myclass
00337 {
00338
00339 ...
00340
00341 private:
00342 myclass (myclass & src);
00343 };
00344 \endcode
00345 This will cause a compilation error if someone ever tries to pass an object
00346 of your class by value.
00347
00348 */