From 033e0b71559af2baae92bdbc948f7b60da6f57cb Mon Sep 17 00:00:00 2001 From: thefiddler Date: Sun, 30 Mar 2014 10:29:11 +0200 Subject: [PATCH] [Bind] Concatenate multiline documentation --- Source/Bind/CSharpSpecWriter.cs | 56 ++++++++++++++++++++++++++------------- Source/Bind/CppSpecWriter.cs | 2 +- Source/Bind/DocProcessor.cs | 51 +++++++++++++++-------------------- Source/Bind/Generator.Bind.csproj | 1 - Source/Bind/JavaSpecWriter.cs | 2 +- 5 files changed, 62 insertions(+), 50 deletions(-) diff --git a/Source/Bind/CSharpSpecWriter.cs b/Source/Bind/CSharpSpecWriter.cs index 6a7eb93..aa1ba07 100644 --- a/Source/Bind/CSharpSpecWriter.cs +++ b/Source/Bind/CSharpSpecWriter.cs @@ -274,7 +274,7 @@ namespace Bind get { if (processor_ == null) - processor_ = new DocProcessor(Path.Combine(Settings.DocPath, Settings.DocFile)); + processor_ = new DocProcessor(); return processor_; } } @@ -310,48 +310,68 @@ namespace Bind new KeyValuePair(p.Name, String.Empty)).ToList() }; - string warning = "[deprecated: v{0}]"; - string category = "[requires: {0}]"; + string warning = String.Empty; + string category = String.Empty; if (f.Deprecated) { - warning = String.Format(warning, f.DeprecatedVersion); - docs.Summary = docs.Summary.Insert(0, warning); + warning = String.Format("[deprecated: v{0}]", f.DeprecatedVersion); } if (f.Extension != "Core" && !String.IsNullOrEmpty(f.Category)) { - category = String.Format(category, f.Category); - docs.Summary = docs.Summary.Insert(0, category); + category = String.Format("[requires: {0}]", f.Category); } else if (!String.IsNullOrEmpty(f.Version)) { if (f.Category.StartsWith("VERSION")) - category = String.Format(category, "v" + f.Version); + category = String.Format("[requires: {0}]", "v" + f.Version); else - category = String.Format(category, "v" + f.Version + " and " + f.Category); - docs.Summary = docs.Summary.Insert(0, category); + category = String.Format("[requires: {0}]", "v" + f.Version + " or " + f.Category); } + sw.WriteLine("/// {0}{1} {2}", + category, warning, docs.Summary); for (int i = 0; i < f.Parameters.Count; i++) { var param = f.Parameters[i]; + + string length = String.Empty; if (!String.IsNullOrEmpty(param.ComputeSize)) { - docs.Parameters[i].Value.Insert(0, - String.Format("[length: {0}]", param.ComputeSize)); + length = String.Format("[length: {0}]", param.ComputeSize); } - } - sw.WriteLine("/// {0}", docs.Summary); - foreach (var p in docs.Parameters) - { - sw.WriteLine("/// {1}", p.Key, p.Value); + if (docs.Parameters.Count > i) + { + var doc = docs.Parameters[i]; + + if (doc.Key != param.Name) + { + Console.Error.WriteLine( + "[Warning] Parameter '{0}' in function '{1}' has incorrect doc name '{2}'", + param.Name, f.Name, doc.Key); + } + + + // Note: we use param.Name, because the documentation sometimes + // uses different names than the specification. + sw.WriteLine("/// {1} {2}", + param.Name, length, doc.Value); + } + else + { + Console.Error.WriteLine( + "[Warning] Parameter '{0}' in function '{1}' not found in '{2}'", + param.Name, f.Name, docfile); + sw.WriteLine("/// {1}", + param.Name, length); + } } } catch (Exception e) { Console.WriteLine("[Warning] Error processing file {0}: {1}", docfile, e.ToString()); - } + } } #endregion diff --git a/Source/Bind/CppSpecWriter.cs b/Source/Bind/CppSpecWriter.cs index e53ffa4..6ead392 100644 --- a/Source/Bind/CppSpecWriter.cs +++ b/Source/Bind/CppSpecWriter.cs @@ -671,7 +671,7 @@ typedef const char* GLstring; get { if (processor_ == null) - processor_ = new DocProcessor(Path.Combine(Settings.DocPath, Settings.DocFile)); + processor_ = new DocProcessor(); return processor_; } } diff --git a/Source/Bind/DocProcessor.cs b/Source/Bind/DocProcessor.cs index 9acfb96..5169e0d 100644 --- a/Source/Bind/DocProcessor.cs +++ b/Source/Bind/DocProcessor.cs @@ -8,7 +8,6 @@ using System.Text.RegularExpressions; using System.Xml; using System.Xml.Linq; using System.Xml.XPath; -using System.Xml.Xsl; using Bind.Structures; @@ -19,29 +18,12 @@ namespace Bind static readonly Regex remove_mathml = new Regex( @"<(mml:math|inlineequation)[^>]*?>(?:.|\n)*?", RegexOptions.Compiled | RegexOptions.Multiline | RegexOptions.IgnorePatternWhitespace); - - static readonly XslCompiledTransform xslt = new XslCompiledTransform(); - static readonly XmlReaderSettings settings = new XmlReaderSettings(); + static readonly Regex remove_doctype = new Regex( + @"\[]*(\[.*\])?>", RegexOptions.Compiled | RegexOptions.Multiline); Documentation Cached; string LastFile; - public DocProcessor(string transform_file) - { - if (!File.Exists(transform_file)) - { - // If no specific transform file exists - // get the generic transform file from - // the parent directory - var dir = Directory.GetParent(Path.GetDirectoryName(transform_file)).FullName; - var file = Path.GetFileName(transform_file); - transform_file = Path.Combine(dir, file); - } - xslt.Load(transform_file); - settings.ProhibitDtd = false; - settings.XmlResolver = null; - } - // Strips MathML tags from the source and replaces the equations with the content // found in the comments in the docs. // Todo: Some simple MathML tags do not include comments, find a solution. @@ -57,10 +39,8 @@ namespace Bind text = File.ReadAllText(file); text = text - .Replace("xml:", String.Empty) // Remove namespaces - .Replace("ε", "epsilon") // Fix unrecognized ε entities - .Replace("", "") // Improve output - .Replace("", ""); + .Replace("ε", "epsilon"); // Fix unrecognized ε entities + text = remove_doctype.Replace(text, String.Empty); Match m = remove_mathml.Match(text); while (m.Length > 0) @@ -98,11 +78,12 @@ namespace Bind { // The pure XmlReader is ~20x faster than the XmlTextReader. //doc = XmlReader.Create(new StringReader(text), settings); + //XmlReader reader = doc = XDocument.Parse(text); Cached = ToInlineDocs(doc); return Cached; } - catch (XmlException e) + catch (Exception e) { Console.WriteLine(e.ToString()); Console.WriteLine(doc.ToString()); @@ -115,19 +96,31 @@ namespace Bind var inline = new Documentation { Summary = - ((IEnumerable)doc.XPathEvaluate("//*[name()='refentry']/*[name()='refnamediv']/*[name()='refpurpose']")) - .Cast().First().Value.Trim(), + Cleanup( + ((IEnumerable)doc.XPathEvaluate("//*[name()='refentry']/*[name()='refnamediv']/*[name()='refpurpose']")) + .Cast().First().Value), Parameters = ((IEnumerable)doc.XPathEvaluate("*[name()='refentry']/*[name()='refsect1'][@id='parameters']/*[name()='variablelist']/*[name()='varlistentry']")) .Cast() - .Select(p => new KeyValuePair( + .Select(p => + new KeyValuePair( p.XPathSelectElement("*[name()='term']/*[name()='parameter']").Value.Trim(), - p.XPathSelectElement("*[name()='listitem']").Value.Trim())) + Cleanup(p.XPathSelectElement("*[name()='listitem']").Value))) .ToList() }; inline.Summary = Char.ToUpper(inline.Summary[0]) + inline.Summary.Substring(1); return inline; } + + static readonly char[] newline = new char[] { '\n' }; + static string Cleanup(string text) + { + return + String.Join(" ", text + .Replace("\r", "\n") + .Split(newline, StringSplitOptions.RemoveEmptyEntries) + .Select(s => s.Trim()).ToArray()); + } } } diff --git a/Source/Bind/Generator.Bind.csproj b/Source/Bind/Generator.Bind.csproj index f6e517c..13241ed 100644 --- a/Source/Bind/Generator.Bind.csproj +++ b/Source/Bind/Generator.Bind.csproj @@ -55,7 +55,6 @@ 4 AllRules.ruleset full - -mode:es30 285212672 diff --git a/Source/Bind/JavaSpecWriter.cs b/Source/Bind/JavaSpecWriter.cs index c7d34aa..576f027 100644 --- a/Source/Bind/JavaSpecWriter.cs +++ b/Source/Bind/JavaSpecWriter.cs @@ -322,7 +322,7 @@ namespace Bind get { if (processor_ == null) - processor_ = new DocProcessor(Path.Combine(Settings.DocPath, Settings.DocFile)); + processor_ = new DocProcessor(); return processor_; } } -- 2.7.4