csharp: Some docs improvements.

Summary:
- Silent missing docs warnign for API delegates
- Document variables
- Better docs for async functions

Reviewers: segfaultxavi, vitor.sousa

Reviewed By: segfaultxavi

Subscribers: cedric, #reviewers, #committers

Tags: #efl

Differential Revision: https://phab.enlightenment.org/D8809

diff --git a/src/bin/eolian_mono/eolian/mono/async_function_definition.hh b/src/bin/eolian_mono/eolian/mono/async_function_definition.hh
index f6a3ff5..b3ab6d4 100644 (file)
--- a/src/bin/eolian_mono/eolian/mono/async_function_definition.hh
+++ b/src/bin/eolian_mono/eolian/mono/async_function_definition.hh
@@ -54,8 +54,20 @@ struct async_function_declaration_generator
       return true;
 
     if (!as_generator(
-            scope_tab << "System.Threading.Tasks.Task<Eina.Value> " << name_helpers::managed_async_method_name(f) << "(" << *(parameter << ",") <<
-                                    " System.Threading.CancellationToken token = default(System.Threading.CancellationToken));\n"
+            scope_tab << "/// <summary>Async wrapper for <see cref=\"" << name_helpers::managed_method_name(f) << "\" />.</summary>\n"
+        ).generate(sink, attributes::unused, context))
+      return false;
+
+    // generate_parameter is not a proper as_generator-compatible generator, so we had to do an old fashioned loop
+    for (auto&& param : f.parameters)
+      if (!documentation(1).generate_parameter(sink, param, context))
+        return false;
+
+    if (!as_generator(
+            scope_tab << "/// <param name=\"token\">Token to notify the async operation of external request to cancel.</param>\n"
+            << scope_tab << "/// <returns>An async task wrapping the result of the operation.</returns>\n"
+            << scope_tab << "System.Threading.Tasks.Task<Eina.Value> " << name_helpers::managed_async_method_name(f) << "(" << *(parameter << ",") <<
+                                    " System.Threading.CancellationToken token = default(System.Threading.CancellationToken));\n\n"
         ).generate(sink, f.parameters, context))
       return false;
 
@@ -88,12 +100,24 @@ struct async_function_definition_generator
 
     std::transform(f.parameters.begin(), f.parameters.end(), std::back_inserter(param_forwarding), parameter_forwarding);
 
+    if (!as_generator(
+            scope_tab << "/// <summary>Async wrapper for <see cref=\"" << name_helpers::managed_method_name(f) << "\" />.</summary>\n"
+        ).generate(sink, attributes::unused, context))
+      return false;
+
+    // generate_parameter is not a proper as_generator-compatible generator, so we had to do an old fashioned loop
+    for (auto&& param : f.parameters)
+      if (!documentation(1).generate_parameter(sink, param, context))
+        return false;
+
     if(!as_generator(
-            scope_tab << "public System.Threading.Tasks.Task<Eina.Value> " << name_helpers::managed_async_method_name(f) << "(" << *(parameter << ",") << " System.Threading.CancellationToken token = default(System.Threading.CancellationToken))\n"
+            scope_tab << "/// <param name=\"token\">Token to notify the async operation of external request to cancel.</param>\n"
+            << scope_tab << "/// <returns>An async task wrapping the result of the operation.</returns>\n"
+            << scope_tab << "public System.Threading.Tasks.Task<Eina.Value> " << name_helpers::managed_async_method_name(f) << "(" << *(parameter << ",") << " System.Threading.CancellationToken token = default(System.Threading.CancellationToken))\n"
             << scope_tab << "{\n"
             << scope_tab << scope_tab << "Eina.Future future = " << name_helpers::managed_method_name(f) << "(" << (string % ",") << ");\n"
             << scope_tab << scope_tab << "return Efl.Eo.Globals.WrapAsync(future, token);\n"
-            << scope_tab << "}\n"
+            << scope_tab << "}\n\n"
         ).generate(sink, std::make_tuple(f.parameters, param_forwarding), context))
       return false;
     return true;

diff --git a/src/bin/eolian_mono/eolian/mono/klass.hh b/src/bin/eolian_mono/eolian/mono/klass.hh
index c81a23f..9d3711f 100644 (file)
--- a/src/bin/eolian_mono/eolian/mono/klass.hh
+++ b/src/bin/eolian_mono/eolian/mono/klass.hh
@@ -465,9 +465,9 @@ struct klass
 
          // Native method definitions
          if(!as_generator(
-                indent << scope_tab << "#pragma warning disable CA1707, SA1300, SA1600\n\n"
+                indent << scope_tab << "#pragma warning disable CA1707, CS1591, SA1300, SA1600\n\n"
                 <<  *(native_function_definition(cls))
-                << indent << scope_tab << "#pragma warning restore CA1707, SA1300, SA1600\n\n")
+                << indent << scope_tab << "#pragma warning restore CA1707, CS1591, SA1300, SA1600\n\n")
             .generate(sink, implementable_methods, change_indentation(indent.inc(), inative_cxt))) return false;
 
          if(!as_generator("}\n").generate(sink, attributes::unused, inative_cxt)) return false;
@@ -516,15 +516,19 @@ struct klass
        return true;
 
      if (cls.get_all_events().size() > 0)
-        if (!as_generator(scope_tab << visibility << "Dictionary<(IntPtr desc, object evtDelegate), (IntPtr evtCallerPtr, Efl.EventCb evtCaller)> eoEvents = new Dictionary<(IntPtr desc, object evtDelegate), (IntPtr evtCallerPtr, Efl.EventCb evtCaller)>();\n"
-                          << scope_tab << visibility << "readonly object eventLock = new object();\n")
+        if (!as_generator(
+                    scope_tab << "/// <summary>Internal usage by derived classes to track native events.</summary>\n"
+                    << scope_tab << visibility << "Dictionary<(IntPtr desc, object evtDelegate), (IntPtr evtCallerPtr, Efl.EventCb evtCaller)> eoEvents = new Dictionary<(IntPtr desc, object evtDelegate), (IntPtr evtCallerPtr, Efl.EventCb evtCaller)>();\n"
+                    << scope_tab << "/// <summary>Internal usage by derived classes to lock native event handlers.</summary>\n"
+                    << scope_tab << visibility << "readonly object eventLock = new object();\n")
               .generate(sink, attributes::unused, context))
           return false;
 
      if (is_inherit)
       {
          if (!as_generator(
-                scope_tab << "protected bool inherited;\n"
+                scope_tab << "/// <summary>Internal usage to detect whether this instance is from a generated class or not.</summary>\n"
+                << scope_tab << "protected bool inherited;\n"
                 ).generate(sink, attributes::unused, context))
            return false;
       }

diff --git a/src/bin/eolian_mono/eolian/mono/struct_definition.hh b/src/bin/eolian_mono/eolian/mono/struct_definition.hh
index d8f0311..14d3f7f 100644 (file)
--- a/src/bin/eolian_mono/eolian/mono/struct_definition.hh
+++ b/src/bin/eolian_mono/eolian/mono/struct_definition.hh
@@ -267,7 +267,8 @@ struct struct_internal_definition_generator
      auto const& indent = current_indentation(context);
      if (!as_generator
          (
-          indent << "///<summary>Internal wrapper for struct " << string << ".</summary>\n"
+          indent << "#pragma warning disable CS1591\n\n"
+          << indent << "///<summary>Internal wrapper for struct " << string << ".</summary>\n"
           << indent << "[StructLayout(LayoutKind.Sequential)]\n"
           << indent << "public struct " << string << "\n"
           << indent << "{\n"
@@ -367,7 +368,9 @@ struct struct_internal_definition_generator
        return false;
 
      // close internal class
-     if(!as_generator(indent << "}\n\n").generate(sink, attributes::unused, context)) return false;
+     if(!as_generator(indent << "}\n\n"
+                      << indent << "#pragma warning restore CS1591\n\n"
+                 ).generate(sink, attributes::unused, context)) return false;
 
      return true;
   }
@@ -435,7 +438,9 @@ struct struct_definition_generator
        }
 
      if(!as_generator(
-            indent << scope_tab << "public static implicit operator " << struct_name << "(IntPtr ptr)\n"
+            indent << scope_tab << "///<summary>Implicit conversion to the managed representation from a native pointer.</summary>\n"
+            << indent << scope_tab << "///<param name=\"ptr\">Native pointer to be converted.</param>\n"
+            << indent << scope_tab << "public static implicit operator " << struct_name << "(IntPtr ptr)\n"
             << indent << scope_tab << "{\n"
             << indent << scope_tab << scope_tab << "var tmp = (" << struct_name << ".NativeStruct)Marshal.PtrToStructure(ptr, typeof(" << struct_name << ".NativeStruct));\n"
             << indent << scope_tab << scope_tab << "return tmp;\n"

diff --git a/src/bin/eolian_mono/eolian/mono/variable_definition.hh b/src/bin/eolian_mono/eolian/mono/variable_definition.hh
index 29211d0..fdc5219 100644 (file)
--- a/src/bin/eolian_mono/eolian/mono/variable_definition.hh
+++ b/src/bin/eolian_mono/eolian/mono/variable_definition.hh
@@ -58,11 +58,12 @@ struct constant_definition_generator
       }
 
     // declare variable
-    if (!as_generator(scope_tab(1)
+    if (!as_generator(documentation(1)
+                      << scope_tab(1)
                       << "public static readonly " << type
                       << " " << utils::remove_all(constant.name, '_')
                       << " = " << literal << ";\n")
-          .generate(sink, constant.base_type, context))
+          .generate(sink, std::make_tuple(constant, constant.base_type), context))
       return false;
 
     // FIXME missing documentation generator