Merge pull request #834 from jskeet/docfixes

Add (some) XML documentation to generated code

csharp/src/AddressBook/Addressbook.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Google.Protobuf.Examples.AddressBook {
 
+  /// <summary>Holder for reflection information generated from addressbook.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class Addressbook {
 
     #region Descriptor
+    /// <summary>File descriptor for addressbook.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }
@@ -212,6 +214,7 @@ namespace Google.Protobuf.Examples.AddressBook {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the Person message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       public enum PhoneType {

csharp/src/Google.Protobuf.Conformance/Conformance.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Conformance {
 
+  /// <summary>Holder for reflection information generated from conformance.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class Conformance {
 
     #region Descriptor
+    /// <summary>File descriptor for conformance.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }
@@ -225,6 +227,7 @@ namespace Conformance {
     }
 
     private object payload_;
+    /// <summary>Enum of possible cases for the "payload" oneof.</summary>
     public enum PayloadOneofCase {
       None = 0,
       ProtobufPayload = 1,
@@ -431,6 +434,7 @@ namespace Conformance {
     }
 
     private object result_;
+    /// <summary>Enum of possible cases for the "result" oneof.</summary>
     public enum ResultOneofCase {
       None = 0,
       ParseError = 1,
@@ -1240,6 +1244,7 @@ namespace Conformance {
     }
 
     private object oneofField_;
+    /// <summary>Enum of possible cases for the "oneof_field" oneof.</summary>
     public enum OneofFieldOneofCase {
       None = 0,
       OneofUint32 = 111,
@@ -2123,6 +2128,7 @@ namespace Conformance {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the TestAllTypes message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       public enum NestedEnum {

csharp/src/Google.Protobuf.Test/TestProtos/MapUnittestProto3.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Google.Protobuf.TestProtos {
 
+  /// <summary>Holder for reflection information generated from google/protobuf/map_unittest_proto3.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class MapUnittestProto3 {
 
     #region Descriptor
+    /// <summary>File descriptor for google/protobuf/map_unittest_proto3.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }
@@ -1305,6 +1307,7 @@ namespace Google.Protobuf.TestProtos {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the MessageContainingEnumCalledType message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       public enum Type {

csharp/src/Google.Protobuf.Test/TestProtos/UnittestImportProto3.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Google.Protobuf.TestProtos {
 
+  /// <summary>Holder for reflection information generated from google/protobuf/unittest_import_proto3.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class UnittestImportProto3 {
 
     #region Descriptor
+    /// <summary>File descriptor for google/protobuf/unittest_import_proto3.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }

csharp/src/Google.Protobuf.Test/TestProtos/UnittestImportPublicProto3.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Google.Protobuf.TestProtos {
 
+  /// <summary>Holder for reflection information generated from google/protobuf/unittest_import_public_proto3.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class UnittestImportPublicProto3 {
 
     #region Descriptor
+    /// <summary>File descriptor for google/protobuf/unittest_import_public_proto3.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }

csharp/src/Google.Protobuf.Test/TestProtos/UnittestIssues.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace UnitTest.Issues.TestProtos {
 
+  /// <summary>Holder for reflection information generated from unittest_issues.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class UnittestIssues {
 
     #region Descriptor
+    /// <summary>File descriptor for unittest_issues.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }
@@ -149,6 +151,7 @@ namespace UnitTest.Issues.TestProtos {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the Issue307 message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -226,6 +229,7 @@ namespace UnitTest.Issues.TestProtos {
         }
 
         #region Nested types
+        /// <summary>Container for nested types declared in the NestedOnce message type.</summary>
         [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
         public static partial class Types {
           [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -981,6 +985,7 @@ namespace UnitTest.Issues.TestProtos {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the ReservedNames message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -1165,6 +1170,7 @@ namespace UnitTest.Issues.TestProtos {
     }
 
     private object o1_;
+    /// <summary>Enum of possible cases for the "o1" oneof.</summary>
     public enum O1OneofCase {
       None = 0,
       O1String = 2,
@@ -1181,6 +1187,7 @@ namespace UnitTest.Issues.TestProtos {
     }
 
     private object o2_;
+    /// <summary>Enum of possible cases for the "o2" oneof.</summary>
     public enum O2OneofCase {
       None = 0,
       O2Int32 = 6,

csharp/src/Google.Protobuf.Test/TestProtos/UnittestProto3.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Google.Protobuf.TestProtos {
 
+  /// <summary>Holder for reflection information generated from google/protobuf/unittest_proto3.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class UnittestProto3 {
 
     #region Descriptor
+    /// <summary>File descriptor for google/protobuf/unittest_proto3.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }
@@ -715,6 +717,7 @@ namespace Google.Protobuf.TestProtos {
     }
 
     private object oneofField_;
+    /// <summary>Enum of possible cases for the "oneof_field" oneof.</summary>
     public enum OneofFieldOneofCase {
       None = 0,
       OneofUint32 = 111,
@@ -1443,6 +1446,7 @@ namespace Google.Protobuf.TestProtos {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the TestAllTypes message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       public enum NestedEnum {
@@ -3056,6 +3060,7 @@ namespace Google.Protobuf.TestProtos {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the TestFieldOrderings message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -4269,6 +4274,7 @@ namespace Google.Protobuf.TestProtos {
     }
 
     private object foo_;
+    /// <summary>Enum of possible cases for the "foo" oneof.</summary>
     public enum FooOneofCase {
       None = 0,
       FooInt = 1,

csharp/src/Google.Protobuf.Test/TestProtos/UnittestWellKnownTypes.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Google.Protobuf.TestProtos {
 
+  /// <summary>Holder for reflection information generated from google/protobuf/unittest_well_known_types.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class UnittestWellKnownTypes {
 
     #region Descriptor
+    /// <summary>File descriptor for google/protobuf/unittest_well_known_types.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }
@@ -1468,6 +1470,7 @@ namespace Google.Protobuf.TestProtos {
     }
 
     private object oneofField_;
+    /// <summary>Enum of possible cases for the "oneof_field" oneof.</summary>
     public enum OneofFieldOneofCase {
       None = 0,
       AnyField = 1,

csharp/src/Google.Protobuf/CodedInputStream.cs

@@ -38,7 +38,7 @@ using System.IO;
 namespace Google.Protobuf
 {
     /// <summary>
-    /// Readings and decodes protocol message fields.
+    /// Reads and decodes protocol message fields.
     /// </summary>
     /// <remarks>
     /// <para>

csharp/src/Google.Protobuf/Reflection/DescriptorProtoFile.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Google.Protobuf.Reflection {
 
+  /// <summary>Holder for reflection information generated from google/protobuf/descriptor.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   internal static partial class DescriptorProtoFile {
 
     #region Descriptor
+    /// <summary>File descriptor for google/protobuf/descriptor.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }
@@ -877,6 +879,7 @@ namespace Google.Protobuf.Reflection {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the DescriptorProto message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -1455,6 +1458,7 @@ namespace Google.Protobuf.Reflection {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the FieldDescriptorProto message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       internal enum Type {
@@ -2776,6 +2780,7 @@ namespace Google.Protobuf.Reflection {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the FileOptions message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       internal enum OptimizeMode {
@@ -3236,6 +3241,7 @@ namespace Google.Protobuf.Reflection {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the FieldOptions message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       internal enum CType {
@@ -4010,6 +4016,7 @@ namespace Google.Protobuf.Reflection {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the UninterpretedOption message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
@@ -4238,6 +4245,7 @@ namespace Google.Protobuf.Reflection {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the SourceCodeInfo message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]

csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs

@@ -252,7 +252,7 @@ namespace Google.Protobuf.Reflection
             {
                 if (fieldType != FieldType.Message)
                 {
-                    throw new InvalidOperationException("MessageType is only valid for enum fields.");
+                    throw new InvalidOperationException("MessageType is only valid for message fields.");
                 }
                 return messageType;
             }

csharp/src/Google.Protobuf/WellKnownTypes/Any.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/any.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Any {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/any.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }

csharp/src/Google.Protobuf/WellKnownTypes/Api.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/api.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Api {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/api.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }

csharp/src/Google.Protobuf/WellKnownTypes/Duration.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/duration.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Duration {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/duration.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }

csharp/src/Google.Protobuf/WellKnownTypes/Empty.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/empty.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Empty {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/empty.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }

csharp/src/Google.Protobuf/WellKnownTypes/FieldMask.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/field_mask.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class FieldMask {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/field_mask.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }

csharp/src/Google.Protobuf/WellKnownTypes/SourceContext.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/source_context.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class SourceContext {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/source_context.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }

csharp/src/Google.Protobuf/WellKnownTypes/Struct.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/struct.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Struct {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/struct.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }
@@ -253,6 +255,7 @@ namespace Google.Protobuf.WellKnownTypes {
     }
 
     private object kind_;
+    /// <summary>Enum of possible cases for the "kind" oneof.</summary>
     public enum KindOneofCase {
       None = 0,
       NullValue = 1,

csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/timestamp.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Timestamp {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/timestamp.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }

csharp/src/Google.Protobuf/WellKnownTypes/Type.cs

@@ -11,10 +11,12 @@ namespace Google.Protobuf.WellKnownTypes {
 
   namespace Proto {
 
+    /// <summary>Holder for reflection information generated from google/protobuf/type.proto</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Type {
 
       #region Descriptor
+      /// <summary>File descriptor for google/protobuf/type.proto</summary>
       public static pbr::FileDescriptor Descriptor {
         get { return descriptor; }
       }
@@ -595,6 +597,7 @@ namespace Google.Protobuf.WellKnownTypes {
     }
 
     #region Nested types
+    /// <summary>Container for nested types declared in the Field message type.</summary>
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
     public static partial class Types {
       public enum Kind {

csharp/src/Google.Protobuf/WellKnownTypes/Wrappers.cs

@@ -9,10 +9,12 @@ using pbr = global::Google.Protobuf.Reflection;
 using scg = global::System.Collections.Generic;
 namespace Google.Protobuf.WellKnownTypes {
 
+  /// <summary>Holder for reflection information generated from google/protobuf/wrappers.proto</summary>
   [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
   public static partial class Wrappers {
 
     #region Descriptor
+    /// <summary>File descriptor for google/protobuf/wrappers.proto</summary>
     public static pbr::FileDescriptor Descriptor {
       get { return descriptor; }
     }

src/google/protobuf/compiler/csharp/csharp_message.cc

@@ -169,6 +169,7 @@ void MessageGenerator::Generate(io::Printer* printer) {
     printer->Print(
       vars,
       "private object $name$_;\n"
+      "/// <summary>Enum of possible cases for the \"$original_name$\" oneof.</summary>\n"
       "public enum $property_name$OneofCase {\n");
     printer->Indent();
     printer->Print("None = 0,\n");
@@ -199,7 +200,10 @@ void MessageGenerator::Generate(io::Printer* printer) {
 
   // Nested messages and enums
   if (HasNestedGeneratedTypes()) {
-    printer->Print("#region Nested types\n"
+    printer->Print(
+      vars,
+      "#region Nested types\n"
+      "/// <summary>Container for nested types declared in the $class_name$ message type.</summary>\n"
       "[global::System.Diagnostics.DebuggerNonUserCodeAttribute()]\n");
     WriteGeneratedCodeAttributes(printer);
     printer->Print("public static partial class Types {\n");

src/google/protobuf/compiler/csharp/csharp_umbrella_class.cc

@@ -135,7 +135,9 @@ void UmbrellaClassGenerator::WriteIntroduction(io::Printer* printer) {
   }
 
   printer->Print(
-    "[global::System.Diagnostics.DebuggerNonUserCodeAttribute()]\n");
+    "/// <summary>Holder for reflection information generated from $file_name$</summary>\n"
+    "[global::System.Diagnostics.DebuggerNonUserCodeAttribute()]\n",
+    "file_name", file_->name());
   WriteGeneratedCodeAttributes(printer);
   printer->Print(
     "$access_level$ static partial class $umbrella_class_name$ {\n"
@@ -148,12 +150,14 @@ void UmbrellaClassGenerator::WriteIntroduction(io::Printer* printer) {
 void UmbrellaClassGenerator::WriteDescriptor(io::Printer* printer) {
   printer->Print(
     "#region Descriptor\n"
+    "/// <summary>File descriptor for $file_name$</summary>\n"
     "public static pbr::FileDescriptor Descriptor {\n"
     "  get { return descriptor; }\n"
     "}\n"
     "private static pbr::FileDescriptor descriptor;\n"
     "\n"
     "static $umbrella_class_name$() {\n",
+    "file_name", file_->name(),
     "umbrella_class_name", umbrellaClassname_);
   printer->Indent();
   printer->Print(