From: <enl...@li...> - 2003-06-27 21:53:51
|
Enlightenment CVS committal Author : mej Project : eterm Module : libast Dir : eterm/libast/src Modified Files: debug.c obj.c Log Message: Fri Jun 27 17:53:29 2003 Michael Jennings (mej) Starting in on the docs for the object system. Yum. =================================================================== RCS file: /cvsroot/enlightenment/eterm/libast/src/debug.c,v retrieving revision 1.7 retrieving revision 1.8 diff -u -3 -r1.7 -r1.8 --- debug.c 10 Apr 2003 21:54:38 -0000 1.7 +++ debug.c 27 Jun 2003 21:53:49 -0000 1.8 @@ -28,11 +28,11 @@ * This file contains all non-cpp-based debugging functionality. * * @author Michael Jennings <me...@et...> - * $Revision: 1.7 $ - * $Date: 2003/04/10 21:54:38 $ + * $Revision: 1.8 $ + * $Date: 2003/06/27 21:53:49 $ */ -static const char cvs_ident[] = "$Id: debug.c,v 1.7 2003/04/10 21:54:38 mej Exp $"; +static const char cvs_ident[] = "$Id: debug.c,v 1.8 2003/06/27 21:53:49 mej Exp $"; #ifdef HAVE_CONFIG_H # include <config.h> @@ -176,5 +176,6 @@ * -# @link DOXGRP_CONF_FSS File State Stack @endlink * -# @link DOXGRP_CONF_CTX Context Handling @endlink * -# @link DOXGRP_OPT Command Line Option Parser @endlink + * -# @link DOXGRP_OBJ Object Infrastructure @endlink * */ =================================================================== RCS file: /cvsroot/enlightenment/eterm/libast/src/obj.c,v retrieving revision 1.11 retrieving revision 1.12 diff -u -3 -r1.11 -r1.12 --- obj.c 19 Feb 2003 21:10:35 -0000 1.11 +++ obj.c 27 Jun 2003 21:53:49 -0000 1.12 @@ -21,7 +21,19 @@ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -static const char cvs_ident[] = "$Id: obj.c,v 1.11 2003/02/19 21:10:35 mej Exp $"; +/** + * @file obj.c + * LibAST Object Infrastructure -- Generic Objects + * + * This file contains the basic object class along with its smaller + * (non-object) analogue, the "null" object. + * + * @author Michael Jennings <me...@et...> + * $Revision: 1.12 $ + * $Date: 2003/06/27 21:53:49 $ + */ + +static const char cvs_ident[] = "$Id: obj.c,v 1.12 2003/06/27 21:53:49 mej Exp $"; #ifdef HAVE_CONFIG_H # include <config.h> @@ -165,3 +177,61 @@ { return SPIF_OBJ_CLASSNAME(self); } + + + +/** + * @defgroup DOXGRP_OBJ LibAST Object Infrastructure + * + * This group of types, functions, and pre-processor macros implements + * a mechanism for defining and utilizing objects in native C. + * + * C, as you well know, is a procedural language. It has no native + * facilities for doing object-oriented programming. And thusly was + * born C++ -- native object facilities with much of the same C syntax + * we all know and love. But C++ has one very big (and fatal, IMHO) + * flaw: it requires a special compiler. + * + * That in and of itself is not the end of the world, but it does + * create a number of issues in terms of portability, standardization, + * speed, and efficiency. Since C has been around for so much longer, + * most C compilers are very stable and reliable, and their + * optimization routines often do almost as good a job as writing raw + * assembly code (particularly the vendor compilers). C++ offers none + * of these types of advantages, and C++ compiler availability has + * historically been sketchy at best. + * + * There are really 2 possible solutions to this, both accomplishing + * the same end result (using the native C compiler to manipulate an + * object model and hierarchy) in two similar, but distinct, ways. + * Both approaches require the use of some sort of preprocessor. + * Option #1 would be to use a dedicated preprocessor, either + * something like m4 or a new creation. This option would probably + * allow for cleaner, more native-looking syntax, but it has similar + * (and potentially worse) portability problems to those of C++. + * + * For these reasons, I chose option #2: a CPP-based (i.e., + * macro-based) object model. As you might imagine, the syntax and + * usage of such a model bears almost no resemblence whatsoever to + * that of a native OO language, as it relies heavily on type-casting + * and namespace safety measures implemented within the existing C/CPP + * structure. However, the resultant code is native C, which means + * you can manipulate data using OO techniques like inheritance, + * interface classes, etc., without incurring the speed/portability + * penalties of using the C++ compiler. Plus, you can build libraries + * that can be easily linked to both C and C++ programs. + * + * If you'd like to see a sample program which demonstrates creation + * and management of LibAST objects, please look here: + * @link obj_example.c @endlink. + */ + +/** + * @example obj_example.c + * Example code for using the LibAST Object Infrastructure + * + * This is a contrived, but informational, example of using LibAST's + * object system. <MORE HERE> + * + * Here's the complete source code: + */ |