diff --git a/SWIG/Doc/Devel/internals.html b/SWIG/Doc/Devel/internals.html index a645cfc54..c185c1f75 100644 --- a/SWIG/Doc/Devel/internals.html +++ b/SWIG/Doc/Devel/internals.html @@ -48,7 +48,7 @@ beazley@cs.uchicago.edu
  • 5. Difference Between SWIG 1.1 and SWIG 1.3
  • 6. Plans for SWIG 2.0
  • 7. C/C++ Wrapper Support Functions -
  • 8. Reserved +
  • 8. Symbol Naming Guidelines for Generated C/C++ Code
  • 9. Reserved
  • 10. Guile Support
  • 11. Python Support @@ -919,8 +919,51 @@ for specifying local variable declarations and argument conversions. -

    8. Reserved

    +

    8. Symbol Naming Guidelines for Generated C/C++ Code

    +The C++ standard (ISO/IEC 14882:1998(E)) states: +
    +
    +
    +17.4.3.1.2 Global names [lib.global.names]
    +
    +1 Certain sets of names and function signatures are always reserved to the implementation:
    +
    +    * Each name that contains a double underscore (__) or begins with an underscore followed 
    +      by an upper case letter (2.11) is reserved to the implementation for any use.
    +    * Each name that begins with an underscore is reserved to the implementation for use as 
    +      a name in the global namespace.165)
    +
    +    165) Such names are also reserved in namespace ::std (17.4.3.1). [back to text] 
    +
    +
    +
    + +When generating code it is important not to generate symbols that might clash with the code being wrapped. It is tempting to flout the standard or just use a symbol which starts with a single underscore followed by a lowercase letter in order to avoid name clashes. However even these legal symbols can also clash with symbols being wrapped. The following guidelines should be used when generating code in order to meet the standard and make it highly unlikely that symbol clashes will occur: +

    + +For C++ code that doesn't attempt to mangle a symbol being wrapped (for example SWIG convenience functions): +

    +

    + +For code compiled as C or C++ that doesn't attempt to mangle a symbol being wrapped (for example SWIG convenience functions): +

    + +For code compiled as C or C++ that attempts to mangle a wrapped symbol: + + +In the past SWIG has generated many symbols which flout the standard especially double underscores. In fact they may not all be rooted out yet, so please fix them when you see them. +

    9. Reserved