Comments.

3 files changed, 51 insertions, 5 deletions

diff --git a/csharp/ProtocolBuffers/ExtensionRegistry.cs b/csharp/ProtocolBuffers/ExtensionRegistry.cs
index c9e05308..dec75733 100644
--- a/csharp/ProtocolBuffers/ExtensionRegistry.cs
+++ b/csharp/ProtocolBuffers/ExtensionRegistry.cs
@@ -19,8 +19,56 @@ using System;
 
 namespace Google.ProtocolBuffers {
   /// <summary>
-  /// TODO(jonskeet): Copy docs from Java
+  /// A table of known extensions, searchable by name or field number.  When
+  /// parsing a protocol message that might have extensions, you must provide
+  /// an <see cref="ExtensionRegistry"/> in which you have registered any extensions
+  /// that you want to be able to parse.  Otherwise, those extensions will just
+  /// be treated like unknown fields.
   /// </summary>
+  /// <example>
+  /// For example, if you had the <c>.proto</c> file:
+  /// <code>
+  /// option java_class = "MyProto";
+  ///
+  /// message Foo {
+  ///   extensions 1000 to max;
+  /// }
+  ///
+  /// extend Foo {
+  ///   optional int32 bar;
+  /// }
+  /// </code>
+  ///
+  /// Then you might write code like:
+  ///
+  /// <code>
+  /// ExtensionRegistry registry = ExtensionRegistry.CreateInstance();
+  /// registry.Add(MyProto.Bar);
+  /// MyProto.Foo message = MyProto.Foo.ParseFrom(input, registry);
+  /// </code>
+  /// </example>
+  ///
+  /// <remarks>
+  /// <para>You might wonder why this is necessary. Two alternatives might come to
+  /// mind. First, you might imagine a system where generated extensions are
+  /// automatically registered when their containing classes are loaded. This
+  /// is a popular technique, but is bad design; among other things, it creates a
+  /// situation where behavior can change depending on what classes happen to be
+  /// loaded. It also introduces a security vulnerability, because an
+  /// unprivileged class could cause its code to be called unexpectedly from a
+  /// privileged class by registering itself as an extension of the right type.
+  /// </para>
+  /// <para>Another option you might consider is lazy parsing: do not parse an
+  /// extension until it is first requested, at which point the caller must
+  /// provide a type to use. This introduces a different set of problems. First,
+  /// it would require a mutex lock any time an extension was accessed, which
+  /// would be slow. Second, corrupt data would not be detected until first
+  /// access, at which point it would be much harder to deal with it. Third, it
+  /// could violate the expectation that message objects are immutable, since the
+  /// type provided could be any arbitrary message class. An unprivileged user
+  /// could take advantage of this to inject a mutable object into a message
+  /// belonging to privileged code and create mischief.</para>
+  /// </remarks>
   public sealed class ExtensionRegistry {
 
     private static readonly ExtensionRegistry empty = new ExtensionRegistry(
@@ -140,7 +188,7 @@ namespace Google.ProtocolBuffers {
           && field.IsOptional
           && field.ExtensionScope == field.MessageType) {
         // This is an extension of a MessageSet type defined within the extension
-        // type's own scope.  For backwards-compatibility, allow it to be looked
+        // type's own scope. For backwards-compatibility, allow it to be looked
         // up by type name.
         extensionsByName[field.MessageType.FullName] = extension;
       }
diff --git a/csharp/ProtocolBuffers/IBuilder.cs b/csharp/ProtocolBuffers/IBuilder.cs
index 44990792..0693d088 100644
--- a/csharp/ProtocolBuffers/IBuilder.cs
+++ b/csharp/ProtocolBuffers/IBuilder.cs
@@ -233,7 +233,6 @@ namespace Google.ProtocolBuffers {
     TBuilder MergeUnknownFields(UnknownFieldSet unknownFields);
 
     #region Convenience methods
-    // TODO(jonskeet): Implement these as extension methods?
     /// <summary>
     /// Parse <paramref name="data"/> as a message of this type and merge
     /// it with the message being built. This is just a small wrapper around
diff --git a/csharp/ProtocolBuffers/InvalidProtocolBufferException.cs b/csharp/ProtocolBuffers/InvalidProtocolBufferException.cs
index 334a416a..10257542 100644
--- a/csharp/ProtocolBuffers/InvalidProtocolBufferException.cs
+++ b/csharp/ProtocolBuffers/InvalidProtocolBufferException.cs
@@ -26,8 +26,7 @@ namespace Google.ProtocolBuffers {
       : base(message) {
     }
 
-    /// TODO(jonskeet): Make this internal again and use InternalVisibleTo?
-    public static InvalidProtocolBufferException TruncatedMessage() {
+    internal static InvalidProtocolBufferException TruncatedMessage() {
       return new InvalidProtocolBufferException(
         "While parsing a protocol message, the input ended unexpectedly " +
         "in the middle of a field.  This could mean either than the " +