Permalink
Browse files

Merge branch 'es_docs' into develop

  • Loading branch information...
2 parents 985aca3 + bd920a1 commit 4ce1289d85d50c2d293f7039b83d26422bac1620 @thefiddler thefiddler committed Apr 2, 2014
Showing 1,346 changed files with 168,006 additions and 65,102 deletions.
@@ -35,6 +35,12 @@
namespace Bind
{
+ enum WriteOptions
+ {
+ Default = 0,
+ NoIndent = 1
+ }
+
class BindStreamWriter : IDisposable
{
static readonly char[] SplitCharacters = new char[] { '\r', '\n' };
@@ -60,7 +66,7 @@ public void Unindent()
--indent_level;
}
- public void Write(string value)
+ public void Write(WriteOptions options, string value)
{
var lines = value.Split(SplitCharacters,
StringSplitOptions.RemoveEmptyEntries);
@@ -71,40 +77,61 @@ public void Write(string value)
for (int i = 0; i < lines.Length - 1; i++)
{
var line = lines[i];
- WriteIndentations();
+ WriteIndentations(options);
sw.Write(line);
sw.Write(System.Environment.NewLine);
}
// Write the last line without appending a newline
- WriteIndentations();
+ WriteIndentations(options);
sw.Write(lines[lines.Length - 1]);
}
else
{
- WriteIndentations();
+ WriteIndentations(options);
sw.Write(value);
}
}
+ public void Write(WriteOptions options, string format, params object[] args)
+ {
+ Write(options, String.Format(format, args));
+ }
+
+ public void Write(string value)
+ {
+ Write(WriteOptions.Default, value);
+ }
+
public void Write(string format, params object[] args)
{
- Write(String.Format(format, args));
+ Write(WriteOptions.Default, format, args);
}
public void WriteLine()
{
sw.WriteLine();
}
- public void WriteLine(string value)
+ public void WriteLine(WriteOptions options, string value)
{
- Write(value);
+ Write(options, value);
WriteLine();
}
+ public void WriteLine(WriteOptions options, string format, params object[] args)
+ {
+ WriteLine(options, String.Format(format, args));
+ }
+
+
+ public void WriteLine(string value)
+ {
+ WriteLine(WriteOptions.Default, value);
+ }
+
public void WriteLine(string format, params object[] args)
{
- WriteLine(String.Format(format, args));
+ WriteLine(WriteOptions.Default, format, args);
}
public void Flush()
@@ -117,10 +144,13 @@ public void Close()
sw.Close();
}
- void WriteIndentations()
+ void WriteIndentations(WriteOptions options)
{
- for (int i = indent_level; i > 0; i--)
- sw.Write(" ");
+ if (options != WriteOptions.NoIndent)
+ {
+ for (int i = indent_level; i > 0; i--)
+ sw.Write(" ");
+ }
}
public void Dispose()
@@ -41,7 +41,6 @@ namespace Bind
sealed class CSharpSpecWriter : ISpecWriter
{
- readonly char[] numbers = "0123456789".ToCharArray();
IBind Generator { get; set; }
Settings Settings { get { return Generator.Settings; } }
@@ -268,89 +267,112 @@ private void WriteMethod(BindStreamWriter sw, Function f, EnumCollection enums)
sw.WriteLine("public static {0} {{ throw new NotImplementedException(); }}", GetDeclarationString(f, Settings.Compatibility));
}
- DocProcessor processor_;
- DocProcessor Processor
- {
- get
- {
- if (processor_ == null)
- processor_ = new DocProcessor(Path.Combine(Settings.DocPath, Settings.DocFile));
- return processor_;
- }
- }
- Dictionary<string, string> docfiles;
void WriteDocumentation(BindStreamWriter sw, Function f)
{
- if (docfiles == null)
- {
- docfiles = new Dictionary<string, string>();
- foreach (string file in Directory.GetFiles(Settings.DocPath))
- {
- docfiles.Add(Path.GetFileName(file), file);
- }
- }
+ var docs = f.Documentation;
- string docfile = null;
try
{
- docfile = Settings.FunctionPrefix + f.WrappedDelegate.Name + ".xml";
- if (!docfiles.ContainsKey(docfile))
- docfile = Settings.FunctionPrefix + f.TrimmedName + ".xml";
- if (!docfiles.ContainsKey(docfile))
- docfile = Settings.FunctionPrefix + f.TrimmedName.TrimEnd(numbers) + ".xml";
-
- var docs = new List<string>();
- if (docfiles.ContainsKey(docfile))
- {
- docs.AddRange(Processor.ProcessFile(docfiles[docfile]));
- }
- if (docs.Count == 0)
- {
- docs.Add("/// <summary></summary>");
- }
-
- int summary_start = docs[0].IndexOf("<summary>") + "<summary>".Length;
- 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[0] = docs[0].Insert(summary_start, warning);
+ warning = String.Format("[deprecated: v{0}]", f.DeprecatedVersion);
}
if (f.Extension != "Core" && !String.IsNullOrEmpty(f.Category))
{
- category = String.Format(category, f.Category);
- docs[0] = docs[0].Insert(summary_start, 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[0] = docs[0].Insert(summary_start, category);
+ category = String.Format("[requires: {0}]", "v" + f.Version + " or " + f.Category);
}
- foreach (var param in f.WrappedDelegate.Parameters)
+ // Write function summary
+ sw.Write("/// <summary>");
+ if (!String.IsNullOrEmpty(category) || !String.IsNullOrEmpty(warning))
{
- var index = docs.IndexOf("/// <param name=\"" + param.Name +"\">");
- if (index != -1 && param.ComputeSize != "")
- {
- var compute_size = string.Format("[length: {0}]", param.ComputeSize);
- docs[index] = docs[index] + compute_size;
- }
+ sw.Write(WriteOptions.NoIndent, "{0}{1}", category, warning);
+ }
+ if (!String.IsNullOrEmpty(docs.Summary))
+ {
+ sw.WriteLine();
+ sw.WriteLine("/// {0}", docs.Summary);
+ sw.WriteLine("/// </summary>");
+ }
+ else
+ {
+ sw.WriteLine(WriteOptions.NoIndent, "</summary>");
}
- foreach (var doc in docs)
+ // Write function parameters
+ for (int i = 0; i < f.Parameters.Count; i++)
{
- sw.WriteLine(doc);
+ var param = f.Parameters[i];
+
+ string length = String.Empty;
+ if (!String.IsNullOrEmpty(param.ComputeSize))
+ {
+ length = String.Format("[length: {0}]", param.ComputeSize);
+ }
+
+ // Try to match the correct parameter from documentation:
+ // - first by name
+ // - then by index
+ var docparam =
+ (docs.Parameters
+ .Where(p => p.Name == param.RawName)
+ .FirstOrDefault()) ??
+ (docs.Parameters.Count > i ?
+ docs.Parameters[i] : null);
+
+ if (docparam != null)
+ {
+ if (docparam.Name != param.RawName &&
+ docparam.Name != param.RawName.Substring(1)) // '@ref' -> 'ref' etc
+ {
+ Console.Error.WriteLine(
+ "[Warning] Parameter '{0}' in function '{1}' has incorrect doc name '{2}'",
+ param.RawName, f.Name, docparam.Name);
+ }
+
+ // Note: we use param.Name, because the documentation sometimes
+ // uses different names than the specification.
+ sw.Write("/// <param name=\"{0}\">", param.Name);
+ if (!String.IsNullOrEmpty(length))
+ {
+ sw.Write(WriteOptions.NoIndent, "{0}", length);
+ }
+ if (!String.IsNullOrEmpty(docparam.Documentation))
+ {
+ sw.WriteLine(WriteOptions.NoIndent, " ");
+ sw.WriteLine("/// {0}", docparam.Documentation);
+ sw.WriteLine("/// </param>");
+ }
+ else
+ {
+ sw.WriteLine(WriteOptions.NoIndent, "</param>");
+ }
+ }
+ else
+ {
+ Console.Error.WriteLine(
+ "[Warning] Parameter '{0}' in function '{1}' not found in documentation '{{{3}}}'",
+ param.Name, f.Name,
+ String.Join(",", docs.Parameters.Select(p => p.Name).ToArray()));
+ sw.WriteLine("/// <param name=\"{0}\">{1}</param>",
+ param.Name, length);
+ }
}
}
catch (Exception e)
{
- Console.WriteLine("[Warning] Error processing file {0}: {1}", docfile, e.ToString());
- }
+ Console.WriteLine("[Warning] Error documenting function {0}: {1}", f.WrappedDelegate.Name, e.ToString());
+ }
}
#endregion
@@ -41,7 +41,6 @@ namespace Bind
sealed class CppSpecWriter : ISpecWriter
{
- readonly char[] numbers = "0123456789".ToCharArray();
const string AllowDeprecated = "GLPP_COMPATIBLE";
const string DigitPrefix = "T"; // Prefix for identifiers that start with a digit
const string OutputFileHeader = "gl++.h";
@@ -665,78 +664,56 @@ static object GenerateCallString(Function f)
return sb.ToString();
}
- DocProcessor processor_;
- DocProcessor Processor
- {
- get
- {
- if (processor_ == null)
- processor_ = new DocProcessor(Path.Combine(Settings.DocPath, Settings.DocFile));
- return processor_;
- }
- }
- Dictionary<string, string> docfiles;
void WriteDocumentation(BindStreamWriter sw, Function f)
{
- if (docfiles == null)
- {
- docfiles = new Dictionary<string, string>();
- foreach (string file in Directory.GetFiles(Settings.DocPath))
- {
- docfiles.Add(Path.GetFileName(file), file);
- }
- }
+ var docs = f.Documentation;
- string docfile = null;
try
{
- docfile = Settings.FunctionPrefix + f.WrappedDelegate.Name + ".xml";
- if (!docfiles.ContainsKey(docfile))
- docfile = Settings.FunctionPrefix + f.TrimmedName + ".xml";
- if (!docfiles.ContainsKey(docfile))
- docfile = Settings.FunctionPrefix + f.TrimmedName.TrimEnd(numbers) + ".xml";
-
- var docs = new List<string>();
- if (docfiles.ContainsKey(docfile))
- {
- docs.AddRange(Processor.ProcessFile(docfiles[docfile]));
- }
- if (docs.Count == 0)
- {
- docs.Add("/// <summary></summary>");
- }
-
- int summary_start = docs[0].IndexOf("<summary>") + "<summary>".Length;
string warning = "[deprecated: v{0}]";
string category = "[requires: {0}]";
if (f.Deprecated)
{
warning = String.Format(warning, f.DeprecatedVersion);
- docs[0] = docs[0].Insert(summary_start, warning);
+ docs.Summary = docs.Summary.Insert(0, warning);
}
if (f.Extension != "Core" && !String.IsNullOrEmpty(f.Category))
{
category = String.Format(category, f.Category);
- docs[0] = docs[0].Insert(summary_start, category);
+ docs.Summary = docs.Summary.Insert(0, category);
}
else if (!String.IsNullOrEmpty(f.Version))
{
if (f.Category.StartsWith("VERSION"))
category = String.Format(category, "v" + f.Version);
else
category = String.Format(category, "v" + f.Version + " and " + f.Category);
- docs[0] = docs[0].Insert(summary_start, category);
+ docs.Summary = docs.Summary.Insert(0, category);
+ }
+
+ for (int i = 0; i < f.WrappedDelegate.Parameters.Count; i++)
+ {
+ var param = f.WrappedDelegate.Parameters[i];
+ if (param.ComputeSize != String.Empty)
+ {
+ docs.Parameters[i].Documentation.Insert(0,
+ String.Format("[length: {0}]", param.ComputeSize));
+ }
}
- foreach (var doc in docs)
+ sw.Write("/// \brief ");
+ sw.WriteLine(docs.Summary);
+ foreach (var p in docs.Parameters)
{
- sw.WriteLine(doc);
+ sw.Write(@"/// \param ");
+ sw.Write(p.Name);
+ sw.WriteLine(p.Documentation);
}
}
catch (Exception e)
{
- Console.WriteLine("[Warning] Error processing file {0}: {1}", docfile, e.ToString());
+ Console.WriteLine("[Warning] Error documenting function {0}: {1}", f.WrappedDelegate.Name, e.ToString());
}
}
Oops, something went wrong.

0 comments on commit 4ce1289

Please sign in to comment.