*** empty log message ***

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@129 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Doc/engineering.html

@@ -17,65 +17,69 @@ beazley@cs.uchicago.edu <br>
 <p>
 <b>$Header$</b>
 
+<p>
+(Note : This is a work in progress.) 
+
 <h2>1. Introduction</h2>
 
 The purpose of this document is to describe various coding conventions
 and organizational aspects for SWIG developers. The idea for this
 document is largely borrowed from John Ousterhout's Tcl/Tk Engineering
-Manual.  It is not my intent to overly managerial about matters--rather the
+Manual.  It is not my intent to overly managerial about matters--rather I'm
-intent is to make life a little less chaotic for everyone involved.
+hoping to make life a little less chaotic for everyone.
 
 <p>
 First a little background: SWIG was started in 1995 as a one-person
-project and continued in this mode until about 1998 (at which point
+project and continued in this mode of operation until about 1998.
-development all but stopped due to some sort of post-dissertation
+Most of this development was driven by ideas submitted by early SWIG
-shock syndrome).  Unfortunately, as a result, the state of the code
+users as opposed to being motivated by a grand design.  As a result,
-can best be described as being a huge hacked up C++ disaster.  A
+the code ended up being a pretty horrible C++ coding disaster.  A
-working disaster, but a disaster nonetheless.   
+mostly working disaster perhaps, but a disaster nonetheless.
 
 <p>
-The primary goal of future SWIG development is to reengineer the
+With that said, the primary goal of future SWIG development is to
-original system and address many of its design flaws and to produce
+reengineer the original system, fix most of its inherent design flaws,
-what can best be described as a highly extensible and modular compiler
+and to produce what I hope will become a highly extensible and modular
-framework.  To this end, there are a few things I want to do.  First,
+interface compiler framework.  To this do this, there are a few
-I want to restructure SWIG as a collection of loosely coupled modules
+critical areas of work.  First, I want to restructure SWIG as a
-written in either ANSI C or scripting languages.  Second, I want the
+collection of loosely coupled modules written in either ANSI C or an
-system to be minimalistic in its use of data structures and
+scripting language.  Second, I want the system to be minimalistic in
-interconnections (e.g., almost all data in the new system is passed
+its use of data structures and interconnections.  The primary reason
-around in hash tables for instance).  The primary reason for this is
+for this is that the fewer data structures there are, the less users
-that the fewer data structures there are, the less you have to
+will have to remember.  This will also make the system more accessible
-remember.  Finally, I was to reevaluate the whole idea of what a SWIG
+to non-experts.  Finally, I want to reevaluate the whole idea of a
-module is and expand the definition to include just about anything
+SWIG module is and expand the definition to include just about
-from parsers, preprocessors, optimizers, interface editors, and code
+anything from parsers, preprocessors, optimizers, interface editors,
-generators.  
+and code generators.
 
 <p>
-The rest of this document describes the basics of how to develop code
+The rest of this document outlines a few general rules of how code
-for SWIG and a few useful guidelines.
+should be developed within the SWIG project.  These rules are
+primarily drawn from my own experience developing software and
+observing the practices of other successful projects.
 
 <h2>2. Programming Languages and Libraries </h2>
 
 All SWIG modules must be written in either ANSI C or one of the
 scripting languages for which SWIG can generate an interface (e.g.,
-Perl, Python, or Tcl).  <B>C++ is NOT an acceptable alternative
+Perl, Python, or Tcl).  <B>C++ is NOT an acceptable alternative and
-and will not be utilized for any future development due to the fact
+will not be utilized for any future development due to the fact that
-that it is too complicated, too problematic, and that Dave would
+it is too complicated, too dogmatic, too problematic, and that Dave would rather
-rather take a bullet to the head than write one more line of code in
+take a bullet to the head than write one more line of code in this
-this most decidedly unpleasant language. </B>
+most decidedly unpleasant language. </B> Rare exceptions to this rule
-Rare exceptions
+may be made if there is a justifiable need to interface an existing
-to this rule may be made if there is a justifiable need to interface
+piece of software written in C++ into the SWIG module system.  Anyone
-an existing piece of software written in C++ into the SWIG module system.
+who finds this rule to be unreasonable is more than welcome to go
-Anyone who finds this rule to be unreasonable is more than welcome to
+write their own wrapper generator--so there.
-go write their own wrapper generator--so there.
 
 <p>
-Modules should make every attempt to use only those functions
+Module writers should make every attempt to use only those functions
 described in the POSIX.1 standard.  This includes most of the
 functions contained the Kernighan and Ritchie C programming book.  Use
 of operating system dependent functionality such as socket libraries
 should always be included inside a conditional compilation block so
-that it can be omitted on problematic platforms.  If you are unsure about a library
+that it can be omitted on problematic platforms.  If you are unsure
-call, check the man page or contact Dave.
+about a library call, check the man page or contact Dave.
 
 <h2>3. The Source Directory and Module Names</h2>
 
@@ -106,10 +110,24 @@ should prevent header-file naming conflicts both within SWIG and when linking
 parts of SWIG to the outside world.
 
 <p>
-All header files should have include guards and be C++ aware.  For example:
+All header files should include a short description, author information, copyright message,
+CVS version, include guards, and be C++ aware. For example:
 
 <blockquote>
 <pre>
+/* -----------------------------------------------------------------------------
+ * swigperl.h
+ *
+ *     All of the externally visible functions in the Perl module.
+ * 
+ * Author(s) : David Beazley (beazley@cs.uchicago.edu)
+ *
+ * Copyright (C) 1999-2000, The University of Chicago.
+ * See the file LICENSE for information on usage and redistribution. 
+ *
+ * $Header$
+ * ----------------------------------------------------------------------------- */
+
 #ifndef _SWIGPERL_H
 #define _SWIGPERL_H   1
 
@@ -140,30 +158,26 @@ are case-insensitive on Windows so this convention will prevent you from inadver
 creating two files that differ in case-only.
 
 <p>
-The structure of each file should include a short copyright message, author information,
+Each file should include a short abstract, author information, copyright information, and
-a CVS revision tag, and an abstract like this:
+a CVS revision tag like this:
 
 <blockquote>
 <pre>
 /* -----------------------------------------------------------------------------
- * Simplified Wrapper and Interface Generator (SWIG)
+ * include.c
+ *
+ *     This file implements the functions used to locate and include files in
+ *     the SWIG library.  Functions for maintaining the library search path are
+ *     also located here.
  * 
  * Author(s) : David Beazley (beazley@cs.uchicago.edu)
  *
- * Copyright (C) 1999-2000, University of Chicago.
+ * Copyright (C) 1999-2000, The University of Chicago.
  * See the file LICENSE for information on usage and redistribution. 
  * ----------------------------------------------------------------------------- */
 
 static char cvsroot[] = "$Header$";
 
-/* -----------------------------------------------------------------------------
- * include.c
- *
- * This file implements the functions used to locate and include files in
- * the SWIG library.  Functions for maintaining the library search path are
- * also located here.
- * ----------------------------------------------------------------------------- */
-
 #include "swig.h"
 
 /* Declarations */
@@ -187,14 +201,14 @@ static int  avariable;
 The CVS revision tag should be placed into a static string as shown
 above.  This adds the revision information to the SWIG executable and
 makes it possible to extract version information from a raw binary
-(sometimes useful in debugging).  Copyright messages do not need to be
+(sometimes useful in debugging).  
-attributed to the University of Chicago provided that the module is
-released under an Open Source copyright that allows redistribution.
 
 <p>
 As a general rule, files start to get unmanagable once they exceed
-about 2000 lines.   Files larger than this should be broken up into
+about 2000 lines.  Files larger than this should be broken up into
-multiple files.
+multiple files.  Similarly, you should avoid the temptation to create
+many small files as this increases compilation time and makes the
+directory structure too complicated.
 
 <h2>6. Bottom-Up Design </h2>
 
@@ -242,7 +256,7 @@ and a short description like this:
 <blockquote>
 <pre>
 /* -----------------------------------------------------------------------------
- * void Swig_add_directory(DOH *dirname)
+ * Swig_add_directory()
  *
  * Adds a directory to the SWIG search path.
  * ----------------------------------------------------------------------------- */
@@ -255,17 +269,23 @@ Swig_add_directory(DOH *dirname) {
 </pre>
 </blockquote>
 
-As for the function declaration itself, the return type and specifiers
+In the function declaration, the return type and any specifiers
 (extern or static) should appear on a separate line followed by the
-function name as shown.
+function name and arguments as shown above.  The left curly brace
+should appear on the same line as the function name.
+
+<p>
+Function declarations should <b>NOT</b> use the pre-ANSI function
+declaration syntax.   The ANSI standard has been around long enough for 
+this to be a non-issue.
 
 <h2>8. Naming Conventions</h2>
 
-The following conventions are generally used to name various objects throughout SWIG.
+The following conventions are used to name various objects throughout SWIG.
 
 <h4>Functions</h4>
 
-Functions should consist of the module name and the function separated by an underscore like this:
+Functions should consist of the module name and the function name separated by an underscore like this:
 
 <blockquote>
 <pre>
@@ -280,7 +300,7 @@ words separated by underscores.
 
 <h4>Structures and Types</h4>
 
-If you module defines structures, the structure name should include the name of the
+If your module defines new structures, the structure name should include the name of the
 module and the name of the structure appended together like this:
 
 <blockquote>
@@ -314,12 +334,12 @@ Constants should be created using #define and should be in all caps like this:
 </pre>
 </blockquote>
 
-Separate words in a constant should be separated by underscores as shown.
+Separate words in a constant should be separated by underscores as with functions.
 
 <h4>Structure members</h4>
 
 Structure members should be in all lower-case and follow the same word-separation convention
-as for function names.  However, the module name does not have to be included on members.
+as for function names.  However, the module name does not have to be included.
 For example:
 
 <blockquote>
@@ -339,12 +359,12 @@ typedef struct SwigScanner {
 
 <h4>Static Functions and Variables </h4>
 
-Static declarations are free to use any naming convention.  However,
+Static declarations are free to use any naming convention that is appropriate. However, most
-most existing parts of the SWIG simply use all lower-case names.
+existing parts of SWIG use lower-case names and follow the same convention as described for functions.
 
 <h2>9. Visibility</h2>
 
-Module should play by the following rules when exposing their interface:
+Modules should keep the following rules in mind when exposing their internals:
 
 <ul>
 <li>Only publicly accessible functions should be included in the module header file.
@@ -354,7 +374,7 @@ to avoid potential linker namespace conflicts with other modules.
 public interface.
 <li>Similarly, modules should discourage the direct manipulation of data contained
 within data structures in favor of using function calls instead.  For example,
-instead of having this:
+instead of providing a user with a structure like this:
 
 <blockquote>
 <pre>
@@ -364,7 +384,7 @@ typedef struct Foo {
 </pre>
 </blockquote>
 
-It is better to simply hide the implementation of Foo and provide an interface like this:
+It is better to hide the implementation of Foo and provide an function-call interface like this:
 
 <blockquote>
 <pre>
@@ -374,10 +394,10 @@ extern void Foo_setline(Foo *f, int line);
 </pre>
 </blockquote>
 
-There are many good reasons for doing this not the least of which is that it allows you
+Although this results in worse performance, there are many practical reasons for doing
-to change the internal representation of Foo without breaking everyone else's module 
+this.  The most important reason is that it allows you to change the internal representation
-(or at the very least having to recompile the universe).
+of Foo without breaking all of the other modules or having to recompile the entire
-
+universe after making your changes.
 
 </body>
 </html>

README

@@ -14,6 +14,8 @@ SWIG release.  The guilty parties working on this are:
 
   -  Dave Beazley (beazley@cs.uchicago.edu)             (SWIG core)
   -  Dustin Mitchell (djmitche@cs.uchicago.edu)         (SWIG core)
+  -  Ian Cooke (iancooke@cs.uchicago.edu)               (SWIG core)
+  -  Bryan King (bwking@midway.uchicago.edu)            (SWIG core)
   -  Loic Dachary (loic@ceic.com)                       (Perl5)
   -  Harco de Hilster (Harco.de.Hilster@ATComputing.nl) (Java)