Improve docs for %rename and C++ features like default args

Doc/Manual/Contents.html

@@ -239,8 +239,8 @@
 <li><a href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>
 <ul>
 <li><a href="SWIGPlus.html#SWIGPlus_nn24">Dispatch function generation</a>
-<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in Overloading</a>
+<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in overloading</a>
-<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
+<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
 <li><a href="SWIGPlus.html#SWIGPlus_nn27">Comments on overloading</a>
 </ul>
 <li><a href="SWIGPlus.html#SWIGPlus_nn28">Overloaded operators</a>

Doc/Manual/Customization.html

@@ -356,7 +356,7 @@ In this case, the exception handler is only attached to declarations
 named "allocate".  This would include both global and member
 functions.  The names supplied to <tt>%exception</tt> follow the same
 rules as for <tt>%rename</tt> described in the section on 
-<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
+<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>.
 For example, if you wanted to define
 an exception handler for a specific class, you might write this:
 </p>
@@ -796,7 +796,7 @@ involving <tt>%feature</tt>:
 </div>
 
 <p>
-The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
+The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
 section applies to all <tt>%feature</tt> directives.
 In fact the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>. 
 The matching rules mean that features are very flexible and can be applied with

Doc/Manual/SWIG.html

@@ -1737,41 +1737,14 @@ careful about namespaces and your use of modules, you can usually
 avoid these problems.</p>
 
 <p>
-<tt>%rename</tt> directive respects function parameters and <i>discriminates default parameters</i> from non-default,
+When wrapping C code, simple use of identifiers/symbols with <tt>%rename</tt> usually suffices.
-which is essential for some languages including Python. Be careful renaming functions having default parameters:
+When wrapping C++ code, simple use of simple identifiers/symbols with <tt>%rename</tt> might be too
+limiting when using C++ features such as function overloading, default arguments, namespaces, template specialization etc.
+If you are using the <tt>%rename</tt> directive and C++, make sure you read the
+<a href="SWIGPlus.html">SWIG and C++</a> chapter and in particular the section on
+<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
+for method overloading and default arguments.
 </p>
-<div class="code"><pre>
-%rename(toFFVal) to_val(FileFormat, bool bin=false);
-int to_val(FileFormat flag, bool bin=false)
-{
-  return 0;
-}
-
-%rename(toDFVal) to_val(DirFormat, bool bin);
-int to_val(DirFormat flag, bool bin=false)
-{
-  return 0;
-}
-
-%rename(toLFVal) to_val(FolderFormat, bool bin);
-int to_val(FolderFormat flag, bool bin=false)
-{
-  return 0;
-}
-</pre></div>
-
-<p>
-The SWIG generator yields the following warning for the last renaming:<br/>
-<tt>
-rename.i:36: Warning 509: Overloaded method to_val(FolderFormat) effectively ignored,<br/>
-rename.i:26: Warning 509: as it is shadowed by to_val(DirFormat).<br/>
-</tt>
-The renaming performed for the <tt>int to_val(FolderFormat flag, bool bin)</tt>,
-but not for the <tt>int to_val(FolderFormat flag)</tt>, where the second parameter <tt>bool bin</tt>
-is omitted taking the default value <tt>false</tt>. See details about the default
-parameters processing in the <a href="SWIGPlus.html#SWIGPlus_default_args">Default Arguments</a> section.
-</p>
-
 
 <p>
 Closely related to <tt>%rename</tt> is the <tt>%ignore</tt> directive.  <tt>%ignore</tt> instructs SWIG
@@ -2115,7 +2088,7 @@ except those consisting of capital letters only:
 <p>
 Finally, variants of <tt>%rename</tt> and <tt>%ignore</tt> directives can be used to help
 wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the
-<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
+<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> section in the C++ chapter.
 </p>
 
 

Doc/Manual/SWIGPlus.html

@@ -42,8 +42,8 @@
 <li><a href="#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>
 <ul>
 <li><a href="#SWIGPlus_nn24">Dispatch function generation</a>
-<li><a href="#SWIGPlus_nn25">Ambiguity in Overloading</a>
+<li><a href="#SWIGPlus_nn25">Ambiguity in overloading</a>
-<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
+<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a>
 <li><a href="#SWIGPlus_nn27">Comments on overloading</a>
 </ul>
 <li><a href="#SWIGPlus_nn28">Overloaded operators</a>
@@ -1772,7 +1772,7 @@ public:
 
 <p>
 The wrappers produced are exactly the same as if the above code was instead fed into SWIG.
-Details of this are covered later in the <a href="#SWIGPlus_overloaded_methods">Overloaded functions and methods</a> section.
+Details of this are covered in the next section <a href="#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>.
 This approach allows SWIG to wrap all possible default arguments, but can be verbose.
 For example if a method has ten default arguments, then eleven wrapper methods are generated.
 </p>
@@ -1780,7 +1780,7 @@ For example if a method has ten default arguments, then eleven wrapper methods a
 <p>
 Please see the <a href="Customization.html#Customization_features_default_args">Features and default arguments</a>
 section for more information on using <tt>%feature</tt> with functions with default arguments.
-The <a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section 
+The <a href="#SWIGPlus_ambiguity_resolution_renaming">Renaming and ambiguity resolution</a> section 
 also deals with using <tt>%rename</tt> and <tt>%ignore</tt> on methods with default arguments.
 If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a <tt>typecheck</tt> typemap.
 See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a> section for details or otherwise
@@ -2031,7 +2031,7 @@ checked in the same order as they appear in this ranking.
 If you're still confused, don't worry about it---SWIG is probably doing the right thing.
 </p>
 
-<H3><a name="SWIGPlus_nn25">6.15.2 Ambiguity in Overloading</a></H3>
+<H3><a name="SWIGPlus_nn25">6.15.2 Ambiguity in overloading</a></H3>
 
 
 <p>
@@ -2149,7 +2149,7 @@ it means that the target language module has not yet implemented support for ove
 functions and methods.  The only way to fix the problem is to read the next section.
 </p>
 
-<H3><a name="SWIGPlus_ambiguity_resolution_renaming">6.15.3 Ambiguity resolution and renaming</a></H3>
+<H3><a name="SWIGPlus_ambiguity_resolution_renaming">6.15.3 Renaming and ambiguity resolution</a></H3>
 
 
 <p>
@@ -2562,8 +2562,7 @@ exactly matches the wrapped method:
 <p>
 The C++ method can then be called from the target language with the new name no matter how many arguments are specified, for example:
 <tt>newbar(2, 2.0)</tt>, <tt>newbar(2)</tt> or <tt>newbar()</tt>.
-However, if the <tt>%rename</tt> does not contain the default arguments, it will only apply to the single equivalent target language overloaded method.
+However, if the <tt>%rename</tt> does not contain the default arguments:
-So if instead we have:
 </p>
 
 <div class="code">
@@ -2572,9 +2571,24 @@ So if instead we have:
 </pre>
 </div>
 
+<p>
+then only one of the three equivalent overloaded methods will be renamed and wrapped as if SWIG parsed:
+</p>
+
+<div class="code">
+<pre>
+void Spam::newbar(int i, double d);
+void Spam::bar(int i);
+void Spam::bar();
+</pre>
+</div>
+
 <p>
 The C++ method must then be called from the target language with the new name <tt>newbar(2, 2.0)</tt> when both arguments are supplied
 or with the original name as <tt>bar(2)</tt> (one argument) or <tt>bar()</tt> (no arguments).
+</p>
+
+<p>
 In fact it is possible to use <tt>%rename</tt> on the equivalent overloaded methods, to rename all the equivalent overloaded methods:
 </p>