Deprecation of the 'nestedworkaround' feature

Also add in macros for the flatnested feature which can be used in place
of the nestedworkaround feature

Doc/Manual/SWIGPlus.html

@@ -4992,11 +4992,27 @@ class Bar {
 
 <p>
 <b>Compatibility Note:</b>
-In SWIG 2.0 and earlier, nested classes were treated as opaque pointers.
-Also there was a workaround, implementing approximately the same behaviour as the
-%feature ("flatnested") with an additional help from the user:
-nested class had to be manually redeclared in the global scope, typedef name and %feature nestedworkaround
-added for the inner class.
+Prior to SWIG-3.0.0, there was limited nested class support. Nested classes were treated as opaque pointers.
+However, there was a workaround for nested class support in these older versions requiring the user to replicate
+the nested class in the global scope, adding in a typedef for the nested class in the global scope and
+using the "nestedworkaround" feature on the nested class. This resulted in approximately the
+same behaviour as the "flatnested" feature. With proper nested class support now available in SWIG-3.0.0, this
+feature has been deprecated and no longer works requiring code changes. If you see the following warning:
+</p>
+
+<div class="shell">
+<pre>
+example.i:8: Warning 126: The nestedworkaround feature is deprecated
+</pre>
+</div>
+
+<p>
+consider using the "flatnested" feature discussed above which generates a non-nested proxy class, like the 
+"nestedworkaround" feature did. Alternatively, use the default nested class code generation, which may generate an
+equivalent to a nested proxy class in the target language, depending on the target language support.
+</p>
+
+<p>
 SWIG-1.3.40 and earlier versions did not have the <tt>nestedworkaround</tt> feature
 and the generated code resulting from parsing nested classes did not always compile.
 Nested class warnings could also not be suppressed using %warnfilter.

Doc/Manual/Warnings.html

@@ -382,6 +382,7 @@ example.i(4) : Syntax error in input.
 <li>119. Deprecated <tt>%typemap(ignore)</tt>.
 <li>120. Deprecated command line option (-runtime, -noruntime).
 <li>121. Deprecated <tt>%name</tt> directive.
+<li>126. The 'nestedworkaround' feature is deprecated.
 </ul>
 
 <H3><a name="Warnings_nn11"></a>14.9.2 Preprocessor (200-299)</H3>

Lib/swig.swg

@@ -9,7 +9,7 @@
  * User Directives 
  * ----------------------------------------------------------------------------- */
 
-/* Deprecated SWIG directives */
+/* Deprecated SWIG-1.1 directives */
 
 #define %disabledoc     %warn "104:%disabledoc is deprecated"
 #define %enabledoc      %warn "105:%enabledoc is deprecated"
@@ -136,11 +136,16 @@
 #define %nocallback     %feature("callback","0")
 #define %clearcallback  %feature("callback","")
 
-/* the %nestedworkaround directive */
+/* the %nestedworkaround directive (deprecated) */
 #define %nestedworkaround       %feature("nestedworkaround")
 #define %nonestedworkaround     %feature("nestedworkaround","0")
 #define %clearnestedworkaround  %feature("nestedworkaround","")
 
+/* the %flatnested directive */
+#define %flatnested       %feature("flatnested")
+#define %noflatnested     %feature("flatnested","0")
+#define %clearflatnested  %feature("flatnested","")
+
 /* the %fastdispatch directive */
 #define %fastdispatch        %feature("fastdispatch")
 #define %nofastdispatch      %feature("fastdispatch","0")

Source/CParse/parser.y

@@ -1080,6 +1080,10 @@ static void single_new_feature(const char *featurename, String *val, Hash *featu
 
   /* Printf(stdout, "single_new_feature: [%s] [%s] [%s] [%s] [%s] [%s]\n", featurename, val, declaratorid, t, ParmList_str_defaultargs(declaratorparms), qualifier); */
 
+  /* Warn about deprecated features */
+  if (strcmp(featurename, "nestedworkaround") == 0)
+    Swig_warning(WARN_DEPRECATED_NESTED_WORKAROUND, cparse_file, cparse_line, "The 'nestedworkaround' feature is deprecated.\n");
+
   fname = NewStringf("feature:%s",featurename);
   if (declaratorid) {
     fixname = feature_identifier_fix(declaratorid);

Source/Include/swigwarn.h

@@ -52,6 +52,7 @@
 #define WARN_DEPRECATED_NODEFAULT     123
 #define WARN_DEPRECATED_TYPEMAP_LANG  124
 #define WARN_DEPRECATED_INPUT_FILE    125
+#define WARN_DEPRECATED_NESTED_WORKAROUND 126
 
 /* -- Preprocessor -- */