[Bind] Use DocumentationParameter instead of KeyValuePair

Source/Bind/CSharpSpecWriter.cs

@@ -307,7 +307,7 @@ namespace Bind
                     {
                         Summary = String.Empty,
                         Parameters = f.Parameters.Select(p =>
-                            new KeyValuePair<string, string>(p.Name, String.Empty)).ToList()
+                            new DocumentationParameter(p.Name, String.Empty)).ToList()
                     };
 
                 string warning = String.Empty;
@@ -341,28 +341,37 @@ namespace Bind
                         length = String.Format("[length: {0}]", param.ComputeSize);
                     }
 
-                    if (docs.Parameters.Count > i)
+                    // Try to match the correct parameter from documentation:
-                    {
+                    // - first by name
-                        var doc = docs.Parameters[i];
+                    // - then by index
+                    var docparam =
+                        (docs.Parameters
+                            .Where(p => p.Name == param.RawName)
+                            .FirstOrDefault()) ??
+                        (docs.Parameters.Count > i ?
+                            docs.Parameters[i] : null);
 
-                        if (doc.Key != param.Name)
+                    if (docparam != null)
+                    {
+                        if (docparam.Name != param.RawName)
                         {
                             Console.Error.WriteLine(
                                 "[Warning] Parameter '{0}' in function '{1}' has incorrect doc name '{2}'",
-                                param.Name, f.Name, doc.Key);
+                                param.Name, f.Name, docparam.Name);
                         }
 
 
                         // Note: we use param.Name, because the documentation sometimes
                         // uses different names than the specification.
                         sw.WriteLine("/// <param name=\"{0}\">{1} {2}</param>",
-                            param.Name, length, doc.Value);
+                            param.Name, length, docparam.Documentation);
                     }
                     else
                     {
                         Console.Error.WriteLine(
-                            "[Warning] Parameter '{0}' in function '{1}' not found in '{2}'",
+                            "[Warning] Parameter '{0}' in function '{1}' not found in '{2}: {{{3}}}'",
-                            param.Name, f.Name, docfile);
+                            param.Name, f.Name, docfile,
+                            String.Join(",", docs.Parameters.Select(p => p.Name).ToArray()));
                         sw.WriteLine("/// <param name=\"{0}\">{1}</param>",
                             param.Name, length);
                     }

Source/Bind/CppSpecWriter.cs

@@ -703,7 +703,7 @@ typedef const char* GLstring;
                     {
                         Summary = String.Empty,
                         Parameters = f.Parameters.Select(p =>
-                            new KeyValuePair<string, string>(p.Name, String.Empty)).ToList()
+                            new DocumentationParameter(p.Name, String.Empty)).ToList()
                     };
 
                 string warning = "[deprecated: v{0}]";
@@ -733,7 +733,7 @@ typedef const char* GLstring;
                     var param = f.WrappedDelegate.Parameters[i];
                     if (param.ComputeSize != String.Empty)
                     {
-                        docs.Parameters[i].Value.Insert(0,
+                        docs.Parameters[i].Documentation.Insert(0,
                             String.Format("[length: {0}]", param.ComputeSize));
                     }
                 }
@@ -743,8 +743,8 @@ typedef const char* GLstring;
                 foreach (var p in docs.Parameters)
                 {
                     sw.Write(@"/// \param ");
-                    sw.Write(p.Key);
+                    sw.Write(p.Name);
-                    sw.WriteLine(p.Value);
+                    sw.WriteLine(p.Documentation);
                 }
             }
             catch (Exception e)

Source/Bind/DocProcessor.cs

@@ -103,7 +103,7 @@ namespace Bind
                     ((IEnumerable)doc.XPathEvaluate("*[name()='refentry']/*[name()='refsect1'][@id='parameters']/*[name()='variablelist']/*[name()='varlistentry']"))
                     .Cast<XNode>()
                     .Select(p =>
-                        new KeyValuePair<string, string>(
+                        new DocumentationParameter(
                             p.XPathSelectElement("*[name()='term']/*[name()='parameter']").Value.Trim(),
                             Cleanup(p.XPathSelectElement("*[name()='listitem']").Value)))
                     .ToList()

Source/Bind/JavaSpecWriter.cs

@@ -354,7 +354,7 @@ namespace Bind
                 {
                     Summary = String.Empty,
                     Parameters = f.Parameters.Select(p =>
-                        new KeyValuePair<string, string>(p.Name, String.Empty)).ToList()
+                        new DocumentationParameter(p.Name, String.Empty)).ToList()
                 };
 
                 string warning = "[deprecated: v{0}]";
@@ -384,7 +384,7 @@ namespace Bind
                     var param = f.WrappedDelegate.Parameters[i];
                     if (param.ComputeSize != String.Empty)
                     {
-                        docs.Parameters[i].Value.Insert(0,
+                        docs.Parameters[i].Documentation.Insert(0,
                             String.Format("[length: {0}]", param.ComputeSize));
                     }
                 }
@@ -392,7 +392,7 @@ namespace Bind
                 sw.WriteLine("/// <summary>{0}</summary>", docs.Summary);
                 foreach (var p in docs.Parameters)
                 {
-                    sw.WriteLine("/// <param name=\"{0}\">{1}</param>", p.Key, p.Value);
+                    sw.WriteLine("/// <param name=\"{0}\">{1}</param>", p.Name, p.Documentation);
                 }
             }
             catch (Exception e)

Source/Bind/Structures/Documentation.cs

@@ -32,10 +32,22 @@ using System.Collections.Generic;
 
 namespace Bind.Structures
 {
-    public class Documentation
+    class Documentation
     {
         public string Summary { get; set; }
-        public List<KeyValuePair<string, string>> Parameters { get; set; }
+        public List<DocumentationParameter> Parameters { get; set; }
+    }
+
+    class DocumentationParameter
+    {
+        public string Name { get; set; }
+        public string Documentation { get; set; }
+
+        public DocumentationParameter(string name, string doc)
+        {
+            Name = name;
+            Documentation = doc;
+        }
     }
 }