You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@avro.apache.org by dk...@apache.org on 2019/08/05 17:42:11 UTC

[avro] branch master updated (1d60c81 -> c0094b5)

This is an automated email from the ASF dual-hosted git repository.

dkulp pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/avro.git.


    from 1d60c81  Fix typos in Javadoc (#601)
     new 3cfebb8  AVRO-2473: Resolve C# documentation warnings
     new c0094b5  AVRO-2473: Treat warnings as errors in C# projects

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 lang/csharp/src/apache/codegen/Avro.codegen.csproj |   5 +
 lang/csharp/src/apache/main/Avro.main.csproj       |   7 +-
 .../apache/main/CodeGen/AvroRuntimeException.cs    |  23 ++-
 lang/csharp/src/apache/main/CodeGen/CodeGen.cs     |  24 +++-
 .../src/apache/main/CodeGen/CodeGenException.cs    |   2 +-
 lang/csharp/src/apache/main/CodeGen/CodeGenUtil.cs |  26 +++-
 lang/csharp/src/apache/main/File/Codec.cs          |  23 +--
 lang/csharp/src/apache/main/File/DataBlock.cs      |  34 ++++-
 .../src/apache/main/File/DataFileConstants.cs      |  57 +++++++-
 lang/csharp/src/apache/main/File/DataFileReader.cs |  88 ++++++++++--
 lang/csharp/src/apache/main/File/DataFileWriter.cs |  56 +++++---
 lang/csharp/src/apache/main/File/DeflateCodec.cs   |  15 +-
 lang/csharp/src/apache/main/File/Header.cs         |  31 ++--
 lang/csharp/src/apache/main/File/IFileReader.cs    |  91 +++++++-----
 lang/csharp/src/apache/main/File/IFileWriter.cs    |  68 +++++----
 lang/csharp/src/apache/main/File/NullCodec.cs      |  18 ++-
 lang/csharp/src/apache/main/Generic/DatumReader.cs |  18 ++-
 lang/csharp/src/apache/main/Generic/DatumWriter.cs |  17 ++-
 .../src/apache/main/Generic/GenericDatumReader.cs  |  15 +-
 .../src/apache/main/Generic/GenericDatumWriter.cs  |  32 +++--
 lang/csharp/src/apache/main/Generic/GenericEnum.cs |  24 +++-
 .../csharp/src/apache/main/Generic/GenericFixed.cs |  29 +++-
 .../src/apache/main/Generic/GenericReader.cs       |  57 +++++++-
 .../src/apache/main/Generic/GenericRecord.cs       |  48 ++++++-
 .../src/apache/main/Generic/GenericWriter.cs       |  74 ++++++++--
 .../apache/main/Generic/PreresolvingDatumReader.cs |  96 ++++++++++++-
 .../apache/main/Generic/PreresolvingDatumWriter.cs | 156 ++++++++++++++++-----
 lang/csharp/src/apache/main/IO/BinaryDecoder.cs    |  96 +++++++++++--
 lang/csharp/src/apache/main/IO/BinaryEncoder.cs    |  30 +++-
 .../src/apache/main/IO/ByteBufferInputStream.cs    |  19 ++-
 .../src/apache/main/IO/ByteBufferOutputStream.cs   |  31 +++-
 lang/csharp/src/apache/main/IO/Decoder.cs          |  14 +-
 lang/csharp/src/apache/main/IO/Encoder.cs          | 140 +++++++++++++++++-
 lang/csharp/src/apache/main/IO/ICallback.cs        |  25 ++--
 lang/csharp/src/apache/main/IO/InputStream.cs      |  14 +-
 lang/csharp/src/apache/main/IO/OutputStream.cs     |  13 +-
 lang/csharp/src/apache/main/IO/Resolver.cs         |   2 +-
 lang/csharp/src/apache/main/Protocol/Message.cs    |  13 +-
 lang/csharp/src/apache/main/Protocol/Protocol.cs   |  11 +-
 .../apache/main/Protocol/ProtocolParseException.cs |  21 ++-
 lang/csharp/src/apache/main/Schema/ArraySchema.cs  |   4 +-
 .../csharp/src/apache/main/Schema/AvroException.cs |  19 ++-
 .../src/apache/main/Schema/AvroTypeException.cs    |  12 +-
 lang/csharp/src/apache/main/Schema/EnumSchema.cs   |   3 +-
 lang/csharp/src/apache/main/Schema/Field.cs        |  15 +-
 lang/csharp/src/apache/main/Schema/FixedSchema.cs  |   3 +-
 lang/csharp/src/apache/main/Schema/JsonHelper.cs   |   2 +-
 lang/csharp/src/apache/main/Schema/MapSchema.cs    |   9 +-
 lang/csharp/src/apache/main/Schema/NamedSchema.cs  |  11 +-
 .../src/apache/main/Schema/PrimitiveSchema.cs      |   4 +-
 lang/csharp/src/apache/main/Schema/Property.cs     |   8 +-
 lang/csharp/src/apache/main/Schema/RecordSchema.cs |  24 +++-
 lang/csharp/src/apache/main/Schema/Schema.cs       |  62 +++++++-
 lang/csharp/src/apache/main/Schema/SchemaName.cs   |   4 +-
 .../src/apache/main/Schema/SchemaNormalization.cs  |  18 ++-
 .../src/apache/main/Schema/SchemaParseException.cs |  14 +-
 lang/csharp/src/apache/main/Schema/UnionSchema.cs  |   4 +-
 .../csharp/src/apache/main/Schema/UnnamedSchema.cs |  12 +-
 .../src/apache/main/Specific/ObjectCreator.cs      |  11 +-
 .../apache/main/Specific/SpecificDatumReader.cs    |  15 +-
 .../apache/main/Specific/SpecificDatumWriter.cs    |  16 ++-
 .../src/apache/main/Specific/SpecificException.cs  |  12 +-
 .../src/apache/main/Specific/SpecificFixed.cs      |  17 ++-
 .../src/apache/main/Specific/SpecificProtocol.cs   |  29 +++-
 .../src/apache/main/Specific/SpecificReader.cs     |  10 +-
 .../src/apache/main/Specific/SpecificRecord.cs     |  25 +++-
 .../src/apache/main/Specific/SpecificWriter.cs     |  13 +-
 lang/csharp/src/apache/msbuild/Avro.msbuild.csproj |   5 +
 lang/csharp/src/apache/perf/Avro.perf.csproj       |   5 +
 lang/csharp/src/apache/test/Avro.test.csproj       |   7 +-
 .../apache/test/Schema/SchemaNormalizationTests.cs |   7 +-
 71 files changed, 1615 insertions(+), 348 deletions(-)


[avro] 02/02: AVRO-2473: Treat warnings as errors in C# projects

Posted by dk...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

dkulp pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/avro.git

commit c0094b5bb1abb79304ce42a56cc115186370d407
Author: Brian Lachniet <bl...@gmail.com>
AuthorDate: Sun Jul 14 08:04:46 2019 -0400

    AVRO-2473: Treat warnings as errors in C# projects
    
    Warnings are only treated as errors in "Release" builds. This allows for
    quicker, iterative development when building "Debug".
---
 lang/csharp/src/apache/codegen/Avro.codegen.csproj | 5 +++++
 lang/csharp/src/apache/main/Avro.main.csproj       | 7 ++++++-
 lang/csharp/src/apache/msbuild/Avro.msbuild.csproj | 5 +++++
 lang/csharp/src/apache/perf/Avro.perf.csproj       | 5 +++++
 lang/csharp/src/apache/test/Avro.test.csproj       | 7 ++++++-
 5 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/lang/csharp/src/apache/codegen/Avro.codegen.csproj b/lang/csharp/src/apache/codegen/Avro.codegen.csproj
index 50fa517..de7fd51 100644
--- a/lang/csharp/src/apache/codegen/Avro.codegen.csproj
+++ b/lang/csharp/src/apache/codegen/Avro.codegen.csproj
@@ -44,6 +44,11 @@
     </Description>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(Configuration)'=='Release'">
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <WarningsAsErrors />
+  </PropertyGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\main\Avro.main.csproj" />
   </ItemGroup>
diff --git a/lang/csharp/src/apache/main/Avro.main.csproj b/lang/csharp/src/apache/main/Avro.main.csproj
index c39371c..4742385 100644
--- a/lang/csharp/src/apache/main/Avro.main.csproj
+++ b/lang/csharp/src/apache/main/Avro.main.csproj
@@ -1,4 +1,4 @@
-<!--
+<!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
@@ -41,6 +41,11 @@
     </Description>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(Configuration)'=='Release'">
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <WarningsAsErrors />
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="Newtonsoft.Json" Version="3.5.8">
       <NoWarn>NU1701</NoWarn>
diff --git a/lang/csharp/src/apache/msbuild/Avro.msbuild.csproj b/lang/csharp/src/apache/msbuild/Avro.msbuild.csproj
index 53c0b69..2383de2 100644
--- a/lang/csharp/src/apache/msbuild/Avro.msbuild.csproj
+++ b/lang/csharp/src/apache/msbuild/Avro.msbuild.csproj
@@ -24,6 +24,11 @@
     <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(Configuration)'=='Release'">
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <WarningsAsErrors />
+  </PropertyGroup>
+
   <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
     <PackageReference Include="Microsoft.Build.Framework" Version="15.6.82" />
     <PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.6.82" />
diff --git a/lang/csharp/src/apache/perf/Avro.perf.csproj b/lang/csharp/src/apache/perf/Avro.perf.csproj
index 37e54e1..725fa6f 100644
--- a/lang/csharp/src/apache/perf/Avro.perf.csproj
+++ b/lang/csharp/src/apache/perf/Avro.perf.csproj
@@ -25,6 +25,11 @@
     <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(Configuration)'=='Release'">
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <WarningsAsErrors />
+  </PropertyGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\main\Avro.main.csproj" />
   </ItemGroup>
diff --git a/lang/csharp/src/apache/test/Avro.test.csproj b/lang/csharp/src/apache/test/Avro.test.csproj
index 6f776fa..a5bd04c 100644
--- a/lang/csharp/src/apache/test/Avro.test.csproj
+++ b/lang/csharp/src/apache/test/Avro.test.csproj
@@ -1,4 +1,4 @@
-<!--
+<!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
@@ -25,6 +25,11 @@
     <GenerateProgramFile>false</GenerateProgramFile>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(Configuration)'=='Release'">
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <WarningsAsErrors />
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="nunit">
       <Version>3.10.1</Version>


[avro] 01/02: AVRO-2473: Resolve C# documentation warnings

Posted by dk...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

dkulp pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/avro.git

commit 3cfebb821f6a34f8600bdef102355e5b8ac2160e
Author: Brian Lachniet <bl...@gmail.com>
AuthorDate: Sat Jul 6 22:23:04 2019 -0400

    AVRO-2473: Resolve C# documentation warnings
    
    - Fix malformed documentation
    - Add missing documentation on public members/types
    - Fix malformed license/copyright headers
    - Removed unneeded 'using' statements
    - Marked some unneeded members/types as 'Obsolete'
---
 .../apache/main/CodeGen/AvroRuntimeException.cs    |  23 ++-
 lang/csharp/src/apache/main/CodeGen/CodeGen.cs     |  24 +++-
 .../src/apache/main/CodeGen/CodeGenException.cs    |   2 +-
 lang/csharp/src/apache/main/CodeGen/CodeGenUtil.cs |  26 +++-
 lang/csharp/src/apache/main/File/Codec.cs          |  23 +--
 lang/csharp/src/apache/main/File/DataBlock.cs      |  34 ++++-
 .../src/apache/main/File/DataFileConstants.cs      |  57 +++++++-
 lang/csharp/src/apache/main/File/DataFileReader.cs |  88 ++++++++++--
 lang/csharp/src/apache/main/File/DataFileWriter.cs |  56 +++++---
 lang/csharp/src/apache/main/File/DeflateCodec.cs   |  15 +-
 lang/csharp/src/apache/main/File/Header.cs         |  31 ++--
 lang/csharp/src/apache/main/File/IFileReader.cs    |  91 +++++++-----
 lang/csharp/src/apache/main/File/IFileWriter.cs    |  68 +++++----
 lang/csharp/src/apache/main/File/NullCodec.cs      |  18 ++-
 lang/csharp/src/apache/main/Generic/DatumReader.cs |  18 ++-
 lang/csharp/src/apache/main/Generic/DatumWriter.cs |  17 ++-
 .../src/apache/main/Generic/GenericDatumReader.cs  |  15 +-
 .../src/apache/main/Generic/GenericDatumWriter.cs  |  32 +++--
 lang/csharp/src/apache/main/Generic/GenericEnum.cs |  24 +++-
 .../csharp/src/apache/main/Generic/GenericFixed.cs |  29 +++-
 .../src/apache/main/Generic/GenericReader.cs       |  57 +++++++-
 .../src/apache/main/Generic/GenericRecord.cs       |  48 ++++++-
 .../src/apache/main/Generic/GenericWriter.cs       |  74 ++++++++--
 .../apache/main/Generic/PreresolvingDatumReader.cs |  96 ++++++++++++-
 .../apache/main/Generic/PreresolvingDatumWriter.cs | 156 ++++++++++++++++-----
 lang/csharp/src/apache/main/IO/BinaryDecoder.cs    |  96 +++++++++++--
 lang/csharp/src/apache/main/IO/BinaryEncoder.cs    |  30 +++-
 .../src/apache/main/IO/ByteBufferInputStream.cs    |  19 ++-
 .../src/apache/main/IO/ByteBufferOutputStream.cs   |  31 +++-
 lang/csharp/src/apache/main/IO/Decoder.cs          |  14 +-
 lang/csharp/src/apache/main/IO/Encoder.cs          | 140 +++++++++++++++++-
 lang/csharp/src/apache/main/IO/ICallback.cs        |  25 ++--
 lang/csharp/src/apache/main/IO/InputStream.cs      |  14 +-
 lang/csharp/src/apache/main/IO/OutputStream.cs     |  13 +-
 lang/csharp/src/apache/main/IO/Resolver.cs         |   2 +-
 lang/csharp/src/apache/main/Protocol/Message.cs    |  13 +-
 lang/csharp/src/apache/main/Protocol/Protocol.cs   |  11 +-
 .../apache/main/Protocol/ProtocolParseException.cs |  21 ++-
 lang/csharp/src/apache/main/Schema/ArraySchema.cs  |   4 +-
 .../csharp/src/apache/main/Schema/AvroException.cs |  19 ++-
 .../src/apache/main/Schema/AvroTypeException.cs    |  12 +-
 lang/csharp/src/apache/main/Schema/EnumSchema.cs   |   3 +-
 lang/csharp/src/apache/main/Schema/Field.cs        |  15 +-
 lang/csharp/src/apache/main/Schema/FixedSchema.cs  |   3 +-
 lang/csharp/src/apache/main/Schema/JsonHelper.cs   |   2 +-
 lang/csharp/src/apache/main/Schema/MapSchema.cs    |   9 +-
 lang/csharp/src/apache/main/Schema/NamedSchema.cs  |  11 +-
 .../src/apache/main/Schema/PrimitiveSchema.cs      |   4 +-
 lang/csharp/src/apache/main/Schema/Property.cs     |   8 +-
 lang/csharp/src/apache/main/Schema/RecordSchema.cs |  24 +++-
 lang/csharp/src/apache/main/Schema/Schema.cs       |  62 +++++++-
 lang/csharp/src/apache/main/Schema/SchemaName.cs   |   4 +-
 .../src/apache/main/Schema/SchemaNormalization.cs  |  18 ++-
 .../src/apache/main/Schema/SchemaParseException.cs |  14 +-
 lang/csharp/src/apache/main/Schema/UnionSchema.cs  |   4 +-
 .../csharp/src/apache/main/Schema/UnnamedSchema.cs |  12 +-
 .../src/apache/main/Specific/ObjectCreator.cs      |  11 +-
 .../apache/main/Specific/SpecificDatumReader.cs    |  15 +-
 .../apache/main/Specific/SpecificDatumWriter.cs    |  16 ++-
 .../src/apache/main/Specific/SpecificException.cs  |  12 +-
 .../src/apache/main/Specific/SpecificFixed.cs      |  17 ++-
 .../src/apache/main/Specific/SpecificProtocol.cs   |  29 +++-
 .../src/apache/main/Specific/SpecificReader.cs     |  10 +-
 .../src/apache/main/Specific/SpecificRecord.cs     |  25 +++-
 .../src/apache/main/Specific/SpecificWriter.cs     |  13 +-
 .../apache/test/Schema/SchemaNormalizationTests.cs |   7 +-
 66 files changed, 1588 insertions(+), 346 deletions(-)

diff --git a/lang/csharp/src/apache/main/CodeGen/AvroRuntimeException.cs b/lang/csharp/src/apache/main/CodeGen/AvroRuntimeException.cs
index dce125f..807597c 100644
--- a/lang/csharp/src/apache/main/CodeGen/AvroRuntimeException.cs
+++ b/lang/csharp/src/apache/main/CodeGen/AvroRuntimeException.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -16,23 +16,34 @@
  * limitations under the License.
  */
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 
 namespace Avro
 {
+    /// <summary>
+    /// A generic Avro exception.
+    /// </summary>
     public class AvroRuntimeException : AvroException
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AvroRuntimeException"/> class.
+        /// </summary>
+        /// <param name="s">The message that describes the error.</param>
         public AvroRuntimeException(string s)
             : base(s)
         {
-
         }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AvroRuntimeException"/> class.
+        /// </summary>
+        /// <param name="s">The message that describes the error.</param>
+        /// <param name="inner">
+        /// The exception that is the cause of the current exception, or a null reference
+        /// if no inner exception is specified.
+        /// </param>
         public AvroRuntimeException(string s, Exception inner)
             : base(s, inner)
         {
-
         }
     }
 }
diff --git a/lang/csharp/src/apache/main/CodeGen/CodeGen.cs b/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
index e6dc0d1..29d7c4d 100644
--- a/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
+++ b/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -27,6 +27,9 @@ using System.IO;
 
 namespace Avro
 {
+    /// <summary>
+    /// Generates C# code from Avro schemas and protocols.
+    /// </summary>
     public class CodeGen
     {
         /// <summary>
@@ -257,7 +260,6 @@ namespace Avro
         /// Creates a class declaration for fixed schema
         /// </summary>
         /// <param name="schema">fixed schema</param>
-        /// <param name="ns">namespace object</param>
         protected virtual void processFixed(Schema schema)
         {
             FixedSchema fixedSchema = schema as FixedSchema;
@@ -311,7 +313,6 @@ namespace Avro
         /// Creates an enum declaration
         /// </summary>
         /// <param name="schema">enum schema</param>
-        /// <param name="ns">namespace</param>
         protected virtual void processEnum(Schema schema)
         {
             EnumSchema enumschema = schema as EnumSchema;
@@ -342,6 +343,10 @@ namespace Avro
             codens.Types.Add(ctd);
         }
 
+        /// <summary>
+        /// Generates code for an individual protocol.
+        /// </summary>
+        /// <param name="protocol">Protocol to generate code for.</param>
         protected virtual void processInterface(Protocol protocol)
         {
             // Create abstract class
@@ -529,8 +534,7 @@ namespace Avro
         /// Creates a class declaration
         /// </summary>
         /// <param name="schema">record schema</param>
-        /// <param name="ns">namespace</param>
-        /// <returns></returns>
+        /// <returns>A new class code type declaration</returns>
         protected virtual CodeTypeDeclaration processRecord(Schema schema)
         {
             RecordSchema recordSchema = schema as RecordSchema;
@@ -677,7 +681,11 @@ namespace Avro
         /// </summary>
         /// <param name="schema">schema</param>
         /// <param name="nullible">flag to indicate union with null</param>
-        /// <returns></returns>
+        /// <param name="nullibleEnum">
+        /// This method sets this value to indicate whether the enum is nullable. True indicates
+        /// that it is nullable. False indicates that it is not nullable.
+        /// </param>
+        /// <returns>Name of the schema's C# type representation.</returns>
         internal static string getType(Schema schema, bool nullible, ref bool nullibleEnum)
         {
             switch (schema.Tag)
@@ -779,6 +787,10 @@ namespace Avro
         /// </summary>
         /// <param name="schema">schema</param>
         /// <param name="ctd">CodeTypeDeclaration for the class</param>
+        /// <param name="overrideFlag">
+        /// Indicates whether we should add the <see cref="MemberAttributes.Override"/> to the
+        /// generated property.
+        /// </param>
         protected virtual void createSchemaField(Schema schema, CodeTypeDeclaration ctd, bool overrideFlag)
         {
             // create schema field
diff --git a/lang/csharp/src/apache/main/CodeGen/CodeGenException.cs b/lang/csharp/src/apache/main/CodeGen/CodeGenException.cs
index 9eafaba..ae2ac61 100644
--- a/lang/csharp/src/apache/main/CodeGen/CodeGenException.cs
+++ b/lang/csharp/src/apache/main/CodeGen/CodeGenException.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
diff --git a/lang/csharp/src/apache/main/CodeGen/CodeGenUtil.cs b/lang/csharp/src/apache/main/CodeGen/CodeGenUtil.cs
index 4738aa1..54de067 100644
--- a/lang/csharp/src/apache/main/CodeGen/CodeGenUtil.cs
+++ b/lang/csharp/src/apache/main/CodeGen/CodeGenUtil.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,9 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
 using System.Collections.Generic;
-using System.Linq;
 using System.Text;
 using System.CodeDom;
 
@@ -28,14 +26,32 @@ namespace Avro
     /// </summary>
     public sealed class CodeGenUtil
     {
-        private static readonly CodeGenUtil instance = new CodeGenUtil();
-        public static CodeGenUtil Instance { get { return instance; } }
+        /// <summary>
+        /// Singleton instance of this class.
+        /// </summary>
+        public static CodeGenUtil Instance { get; } = new CodeGenUtil();
 
+        /// <summary>
+        /// Namespaces to import in generated code.
+        /// </summary>
         public CodeNamespaceImport[] NamespaceImports { get; private set; }
+
+        /// <summary>
+        /// Comment included at the top of each generated code file.
+        /// </summary>
         public CodeCommentStatement FileComment { get; private set; }
+
+        /// <summary>
+        /// Reserved keywords in the C# language.
+        /// </summary>
         public HashSet<string> ReservedKeywords { get; private set; }
+
         private const char At = '@';
         private const char Dot = '.';
+
+        /// <summary>
+        /// Fully-qualified name of a <see cref="Object"/> type.
+        /// </summary>
         public const string Object = "System.Object";
 
         private CodeGenUtil()
diff --git a/lang/csharp/src/apache/main/File/Codec.cs b/lang/csharp/src/apache/main/File/Codec.cs
index b4adc48..14ab07b 100644
--- a/lang/csharp/src/apache/main/File/Codec.cs
+++ b/lang/csharp/src/apache/main/File/Codec.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,15 +15,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.IO;
 
 namespace Avro.File
 {
-    abstract public class Codec
+    /// <summary>
+    /// Base class for Avro-supported compression codecs for data files. Note that Codec objects may
+    /// maintain internal state (e.g. buffers) and are not thread safe.
+    /// </summary>
+    public abstract class Codec
     {
         /// <summary>
         /// Compress data using implemented codec
@@ -64,8 +63,16 @@ namespace Avro.File
         /// </summary>
         public enum Type
         {
+            /// <summary>
+            /// Codec type that implments the "deflate" compression algorithm.
+            /// </summary>
             Deflate,
+
             //Snappy
+
+            /// <summary>
+            /// Codec that does not perform any compression.
+            /// </summary>
             Null
         };
 
@@ -112,4 +119,4 @@ namespace Avro.File
             return GetName();
         }
     }
-}
\ No newline at end of file
+}
diff --git a/lang/csharp/src/apache/main/File/DataBlock.cs b/lang/csharp/src/apache/main/File/DataBlock.cs
index 9feb44c..7fd85e7 100644
--- a/lang/csharp/src/apache/main/File/DataBlock.cs
+++ b/lang/csharp/src/apache/main/File/DataBlock.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,24 +15,44 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+using System;
 using System.IO;
-using Avro.IO;
-using Avro.Generic;
-using System.Collections.Generic;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Encapsulates a block of data read by the <see cref="DataFileReader{T}"/>.
+    /// We will remove this class from the public API in a future version because it is only meant
+    /// to be used internally.
+    /// </summary>
+    [Obsolete("This will be removed from the public API in a future version.")]
     public class DataBlock
     {
+        /// <summary>
+        /// Raw bytes within this block.
+        /// </summary>
         public byte[] Data { get;  set; }
+
+        /// <summary>
+        /// Number of entries in this block.
+        /// </summary>
         public long NumberOfEntries { get; set; }
+
+        /// <summary>
+        /// Size of this block in bytes.
+        /// </summary>
         public long BlockSize { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DataBlock"/> class.
+        /// </summary>
+        /// <param name="numberOfEntries">Number of entries in this block.</param>
+        /// <param name="blockSize">Size of this block in bytes.</param>
         public DataBlock(long numberOfEntries, long blockSize)
         {
-            this.NumberOfEntries = numberOfEntries;
-            this.BlockSize = blockSize;
-            this.Data = new byte[blockSize];
+            NumberOfEntries = numberOfEntries;
+            BlockSize = blockSize;
+            Data = new byte[blockSize];
         }
 
         internal Stream GetDataAsStream()
diff --git a/lang/csharp/src/apache/main/File/DataFileConstants.cs b/lang/csharp/src/apache/main/File/DataFileConstants.cs
index d17cd14..10fe24f 100644
--- a/lang/csharp/src/apache/main/File/DataFileConstants.cs
+++ b/lang/csharp/src/apache/main/File/DataFileConstants.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,32 +15,77 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Constants used in data files.
+    /// </summary>
     public class DataFileConstants
     {
+        /// <summary>
+        /// Key for the 'sync' metadata entry.
+        /// </summary>
         public const string MetaDataSync = "avro.sync";
+
+        /// <summary>
+        /// Key for the 'codec' metadata entry.
+        /// </summary>
         public const string MetaDataCodec = "avro.codec";
+
+        /// <summary>
+        /// Key for the 'schema' metadata entry.
+        /// </summary>
         public const string MetaDataSchema = "avro.schema";
+
+        /// <summary>
+        /// Identifier for the null codec.
+        /// </summary>
         public const string NullCodec = "null";
+
+        /// <summary>
+        /// Identifier for the deflate codec.
+        /// </summary>
         public const string DeflateCodec = "deflate";
+
+        /// <summary>
+        /// Reserved 'avro' metadata key.
+        /// </summary>
         public const string MetaDataReserved = "avro";
 
+        /// <summary>
+        /// Avro specification version.
+        /// </summary>
         public const int Version = 1;
+
+        /// <summary>
+        /// Magic bytes at the beginning of an Avro data file.
+        /// </summary>
         public static byte[] Magic = { (byte)'O',
                                        (byte)'b',
                                        (byte)'j',
-                                       (byte)Version };
+                                       Version };
 
+        /// <summary>
+        /// Hash code for the null codec.
+        /// </summary>
+        /// <seealso cref="NullCodec.GetHashCode()"/>
         public const int NullCodecHash = 2;
+
+        /// <summary>
+        /// Hash code for the deflate codec.
+        /// </summary>
+        /// <seealso cref="DeflateCodec.GetHashCode()"/>
         public const int DeflateCodecHash = 0;
 
+        /// <summary>
+        /// Size of a sync token in bytes.
+        /// </summary>
         public const int SyncSize = 16;
+
+        /// <summary>
+        /// Default interval for sync tokens.
+        /// </summary>
         public const int DefaultSyncInterval = 4000 * SyncSize;
     }
 }
diff --git a/lang/csharp/src/apache/main/File/DataFileReader.cs b/lang/csharp/src/apache/main/File/DataFileReader.cs
index 64483db..6e61d39 100644
--- a/lang/csharp/src/apache/main/File/DataFileReader.cs
+++ b/lang/csharp/src/apache/main/File/DataFileReader.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -25,8 +25,19 @@ using Avro.Specific;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Provides access to Avro data written using the <see cref="DataFileWriter{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">Type to deserialze data objects to.</typeparam>
     public class DataFileReader<T> : IFileReader<T>
     {
+        /// <summary>
+        /// Defines the signature for a function that returns a new <see cref="DatumReader{T}"/>
+        /// given a writer and reader schema.
+        /// </summary>
+        /// <param name="writerSchema">Schema used to write the datum.</param>
+        /// <param name="readerSchema">Schema used to read the datum.</param>
+        /// <returns>A datum reader.</returns>
         public delegate DatumReader<T> CreateDatumReader(Schema writerSchema, Schema readerSchema);
 
         private DatumReader<T> _reader;
@@ -56,8 +67,9 @@ namespace Avro.File
         /// <summary>
         ///  Open a reader for a file using path and the reader's schema
         /// </summary>
-        /// <param name="path"></param>
-        /// <returns></returns>
+        /// <param name="path">Path to the file</param>
+        /// <param name="readerSchema">Schema used to read data from the file</param>
+        /// <returns>A new file reader</returns>
         public static IFileReader<T> OpenReader(string path, Schema readerSchema)
         {
             return OpenReader(new FileStream(path, FileMode.Open), readerSchema);
@@ -74,21 +86,23 @@ namespace Avro.File
         }
 
         /// <summary>
-        ///  Open a reader for a stream using the reader's schema
+        /// Open a reader for a stream using the reader's schema
         /// </summary>
-        /// <param name="inStream"></param>
-        /// <returns></returns>
+        /// <param name="inStream">Stream containing the file contents</param>
+        /// <param name="readerSchema">Schema used to read the file</param>
+        /// <returns>A new file reader</returns>
         public static IFileReader<T> OpenReader(Stream inStream, Schema readerSchema)
         {
             return OpenReader(inStream, readerSchema, CreateDefaultReader);
         }
 
-
         /// <summary>
         ///  Open a reader for a stream using the reader's schema and a custom DatumReader
         /// </summary>
-        /// <param name="inStream"></param>
-        /// <returns></returns>
+        /// <param name="inStream">Stream of file contents</param>
+        /// <param name="readerSchema">Schema used to read the file</param>
+        /// <param name="datumReaderFactory">Factory to create datum readers given a reader an writer schema</param>
+        /// <returns>A new file reader</returns>
         public static IFileReader<T> OpenReader(Stream inStream, Schema readerSchema, CreateDatumReader datumReaderFactory)
         {
             if (!inStream.CanSeek)
@@ -117,21 +131,25 @@ namespace Avro.File
             BlockFinished();
         }
 
+        /// <inheritdoc/>
         public Header GetHeader()
         {
             return _header;
         }
 
+        /// <inheritdoc/>
         public Schema GetSchema()
         {
             return _header.Schema;
         }
 
+        /// <inheritdoc/>
         public ICollection<string> GetMetaKeys()
         {
             return _header.MetaData.Keys;
         }
 
+        /// <inheritdoc/>
         public byte[] GetMeta(string key)
         {
             try
@@ -144,11 +162,13 @@ namespace Avro.File
             }
         }
 
+        /// <inheritdoc/>
         public long GetMetaLong(string key)
         {
             return long.Parse(GetMetaString(key));
         }
 
+        /// <inheritdoc/>
         public string GetMetaString(string key)
         {
             byte[] value = GetMeta(key);
@@ -166,6 +186,7 @@ namespace Avro.File
             }
         }
 
+        /// <inheritdoc/>
         public void Seek(long position)
         {
             _stream.Position = position;
@@ -175,6 +196,7 @@ namespace Avro.File
             _blockStart = position;
         }
 
+        /// <inheritdoc/>
         public void Sync(long position)
         {
             Seek(position);
@@ -203,21 +225,25 @@ namespace Avro.File
             _blockStart = _stream.Position;
         }
 
+        /// <inheritdoc/>
         public bool PastSync(long position)
         {
             return ((_blockStart >= position + DataFileConstants.SyncSize) || (_blockStart >= _stream.Length));
         }
 
+        /// <inheritdoc/>
         public long PreviousSync()
         {
             return _blockStart;
         }
 
+        /// <inheritdoc/>
         public long Tell()
         {
             return _stream.Position;
         }
 
+        /// <inheritdoc/>
         public IEnumerable<T> NextEntries
         {
             get
@@ -229,6 +255,7 @@ namespace Avro.File
             }
         }
 
+        /// <inheritdoc/>
         public bool HasNext()
         {
             try
@@ -253,11 +280,15 @@ namespace Avro.File
             }
         }
 
+        /// <summary>
+        /// Resets this reader.
+        /// </summary>
         public void Reset()
         {
             Init(_stream);
         }
 
+        /// <inheritdoc/>
         public void Dispose()
         {
             _stream.Close();
@@ -328,6 +359,7 @@ namespace Avro.File
             return Codec.CreateCodecFromString(GetMetaString(DataFileConstants.MetaDataCodec));
         }
 
+        /// <inheritdoc/>
         public T Next()
         {
             return Next(default(T));
@@ -421,5 +453,43 @@ namespace Avro.File
                 throw new AvroRuntimeException(string.Format("Error ascertaining if data has next block: {0}", e), e);
             }
         }
+
+        /// <summary>
+        /// Encapsulates a block of data read by the <see cref="DataFileReader{T}"/>.
+        /// </summary>
+        private class DataBlock
+        {
+            /// <summary>
+            /// Raw bytes within this block.
+            /// </summary>
+            public byte[] Data { get;  set; }
+
+            /// <summary>
+            /// Number of entries in this block.
+            /// </summary>
+            public long NumberOfEntries { get; set; }
+
+            /// <summary>
+            /// Size of this block in bytes.
+            /// </summary>
+            public long BlockSize { get; set; }
+
+            /// <summary>
+            /// Initializes a new instance of the <see cref="DataBlock"/> class.
+            /// </summary>
+            /// <param name="numberOfEntries">Number of entries in this block.</param>
+            /// <param name="blockSize">Size of this block in bytes.</param>
+            public DataBlock(long numberOfEntries, long blockSize)
+            {
+                NumberOfEntries = numberOfEntries;
+                BlockSize = blockSize;
+                Data = new byte[blockSize];
+            }
+
+            internal Stream GetDataAsStream()
+            {
+                return new MemoryStream(Data);
+            }
+        }
     }
 }
diff --git a/lang/csharp/src/apache/main/File/DataFileWriter.cs b/lang/csharp/src/apache/main/File/DataFileWriter.cs
index 49e7010..fc666cf 100644
--- a/lang/csharp/src/apache/main/File/DataFileWriter.cs
+++ b/lang/csharp/src/apache/main/File/DataFileWriter.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -24,6 +24,14 @@ using Avro.Generic;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Stores in a file a sequence of data conforming to a schema. The schema is stored in the file
+    /// with the data. Each datum in a file is of the same schema. Data is written with a
+    /// <see cref="DatumWriter{T}"/>. Data is grouped into blocks. A synchronization marker is
+    /// written between blocks, so that files may be split. Blocks may be compressed. Extensible
+    /// metadata is stored at the end of the file. Files may be appended to.
+    /// </summary>
+    /// <typeparam name="T">Type of datum to write to the file.</typeparam>
     public class DataFileWriter<T> : IFileWriter<T>
     {
         private Schema _schema;
@@ -44,9 +52,9 @@ namespace Avro.File
         /// Open a new writer instance to write
         /// to a file path, using a Null codec
         /// </summary>
-        /// <param name="writer"></param>
-        /// <param name="path"></param>
-        /// <returns></returns>
+        /// <param name="writer">Datum writer to use.</param>
+        /// <param name="path">Path to the file.</param>
+        /// <returns>A new file writer.</returns>
         public static IFileWriter<T> OpenWriter(DatumWriter<T> writer, string path)
         {
             return OpenWriter(writer, new FileStream(path, FileMode.Create), Codec.CreateCodec(Codec.Type.Null));
@@ -56,9 +64,9 @@ namespace Avro.File
         /// Open a new writer instance to write
         /// to an output stream, using a Null codec
         /// </summary>
-        /// <param name="writer"></param>
-        /// <param name="outStream"></param>
-        /// <returns></returns>
+        /// <param name="writer">Datum writer to use.</param>
+        /// <param name="outStream">Stream to write to.</param>
+        /// <returns>A new file writer.</returns>
         public static IFileWriter<T> OpenWriter(DatumWriter<T> writer, Stream outStream)
         {
             return OpenWriter(writer, outStream, Codec.CreateCodec(Codec.Type.Null));
@@ -68,10 +76,10 @@ namespace Avro.File
         /// Open a new writer instance to write
         /// to a file path with a specified codec
         /// </summary>
-        /// <param name="writer"></param>
-        /// <param name="path"></param>
-        /// <param name="codec"></param>
-        /// <returns></returns>
+        /// <param name="writer">Datum writer to use.</param>
+        /// <param name="path">Path to the file.</param>
+        /// <param name="codec">Codec to use when writing.</param>
+        /// <returns>A new file writer.</returns>
         public static IFileWriter<T> OpenWriter(DatumWriter<T> writer, string path, Codec codec)
         {
             return OpenWriter(writer, new FileStream(path, FileMode.Create), codec);
@@ -81,10 +89,10 @@ namespace Avro.File
         /// Open a new writer instance to write
         /// to an output stream with a specified codec
         /// </summary>
-        /// <param name="writer"></param>
-        /// <param name="outStream"></param>
-        /// <param name="codec"></param>
-        /// <returns></returns>
+        /// <param name="writer">Datum writer to use.</param>
+        /// <param name="outStream">Stream to write to.</param>
+        /// <param name="codec">Codec to use when writing.</param>
+        /// <returns>A new file writer.</returns>
         public static IFileWriter<T> OpenWriter(DatumWriter<T> writer, Stream outStream, Codec codec)
         {
             return new DataFileWriter<T>(writer).Create(writer.Schema, outStream, codec);
@@ -96,12 +104,14 @@ namespace Avro.File
             _syncInterval = DataFileConstants.DefaultSyncInterval;
         }
 
+        /// <inheritdoc/>
         public bool IsReservedMeta(string key)
         {
             return key.StartsWith(DataFileConstants.MetaDataReserved);
         }
 
-        public void SetMeta(String key, byte[] value)
+        /// <inheritdoc/>
+        public void SetMeta(string key, byte[] value)
         {
             if (IsReservedMeta(key))
             {
@@ -110,7 +120,8 @@ namespace Avro.File
             _metaData.Add(key, value);
         }
 
-        public void SetMeta(String key, long value)
+        /// <inheritdoc/>
+        public void SetMeta(string key, long value)
         {
             try
             {
@@ -122,7 +133,8 @@ namespace Avro.File
             }
         }
 
-        public void SetMeta(String key, string value)
+        /// <inheritdoc/>
+        public void SetMeta(string key, string value)
         {
             try
             {
@@ -134,6 +146,7 @@ namespace Avro.File
             }
         }
 
+        /// <inheritdoc/>
         public void SetSyncInterval(int syncInterval)
         {
             if (syncInterval < 32 || syncInterval > (1 << 30))
@@ -143,6 +156,7 @@ namespace Avro.File
             _syncInterval = syncInterval;
         }
 
+        /// <inheritdoc/>
         public void Append(T datum)
         {
             AssertOpen();
@@ -172,12 +186,14 @@ namespace Avro.File
             }
         }
 
+        /// <inheritdoc/>
         public void Flush()
         {
             EnsureHeader();
             Sync();
         }
 
+        /// <inheritdoc/>
         public long Sync()
         {
             AssertOpen();
@@ -185,6 +201,7 @@ namespace Avro.File
             return _stream.Position;
         }
 
+        /// <inheritdoc/>
         public void Close()
         {
             EnsureHeader();
@@ -243,7 +260,7 @@ namespace Avro.File
             int size = _metaData.Count;
             _encoder.WriteInt(size);
 
-            foreach (KeyValuePair<String, byte[]> metaPair in _metaData)
+            foreach (KeyValuePair<string, byte[]> metaPair in _metaData)
             {
                 _encoder.WriteString(metaPair.Key);
                 _encoder.WriteBytes(metaPair.Value);
@@ -307,6 +324,7 @@ namespace Avro.File
             return System.Text.Encoding.UTF8.GetBytes(value);
         }
 
+        /// <inheritdoc/>
         public void Dispose()
         {
             Close();
diff --git a/lang/csharp/src/apache/main/File/DeflateCodec.cs b/lang/csharp/src/apache/main/File/DeflateCodec.cs
index 76730cc..77f9ee8 100644
--- a/lang/csharp/src/apache/main/File/DeflateCodec.cs
+++ b/lang/csharp/src/apache/main/File/DeflateCodec.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,17 +15,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 using System.IO;
 using System.IO.Compression;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Implements deflate compression and decompression.
+    /// </summary>
+    /// <seealso cref="DeflateStream"/>
     public class DeflateCodec : Codec
     {
+        /// <inheritdoc/>
         public override byte[] Compress(byte[] uncompressedData)
         {
             MemoryStream outStream = new MemoryStream();
@@ -39,6 +40,7 @@ namespace Avro.File
             return outStream.ToArray();
         }
 
+        /// <inheritdoc/>
         public override byte[] Decompress(byte[] compressedData)
         {
             MemoryStream inStream = new MemoryStream(compressedData);
@@ -63,11 +65,13 @@ namespace Avro.File
             }
         }
 
+        /// <inheritdoc/>
         public override string GetName()
         {
             return DataFileConstants.DeflateCodec;
         }
 
+        /// <inheritdoc/>
         public override bool Equals(object other)
         {
             if (this == other)
@@ -75,6 +79,7 @@ namespace Avro.File
             return (this.GetType().Name == other.GetType().Name);
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             return DataFileConstants.DeflateCodecHash;
diff --git a/lang/csharp/src/apache/main/File/Header.cs b/lang/csharp/src/apache/main/File/Header.cs
index a6aa624..1ad2216 100644
--- a/lang/csharp/src/apache/main/File/Header.cs
+++ b/lang/csharp/src/apache/main/File/Header.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,26 +15,37 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
 using System.Collections.Generic;
-using System.Linq;
-using Avro.IO;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Header on an Avro data file.
+    /// </summary>
     public class Header
     {
-        private IDictionary<string, byte[]> _metaData;
-        private byte[] _syncData;
+        /// <summary>
+        /// Metadata in this header.
+        /// </summary>
+        public IDictionary<string, byte[]> MetaData { get; }
 
-        public IDictionary<string, byte[]> MetaData { get { return _metaData; }}
-        public byte[] SyncData { get { return _syncData; }}
+        /// <summary>
+        /// Sync token.
+        /// </summary>
+        public byte[] SyncData { get; }
+
+        /// <summary>
+        /// Avro schema.
+        /// </summary>
         public Schema Schema { get; set; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Header"/> class.
+        /// </summary>
         public Header()
         {
-            _metaData = new Dictionary<string, byte[]>();
-            _syncData = new byte[16];
+            MetaData = new Dictionary<string, byte[]>();
+            SyncData = new byte[16];
         }
     }
 }
diff --git a/lang/csharp/src/apache/main/File/IFileReader.cs b/lang/csharp/src/apache/main/File/IFileReader.cs
index 60e8fea..a4defd2 100644
--- a/lang/csharp/src/apache/main/File/IFileReader.cs
+++ b/lang/csharp/src/apache/main/File/IFileReader.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -17,103 +17,120 @@
  */
 using System;
 using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Defines the interface for an object that reads data from a file.
+    /// </summary>
+    /// <typeparam name="T">Type to serialize data to.</typeparam>
     public interface IFileReader<T> : IDisposable
     {
         /// <summary>
-        /// Return the header for the input
-        /// file / stream
+        /// Return the header for the input file or stream.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>Parsed header from the file or stream.</returns>
         Header GetHeader();
 
         /// <summary>
-        /// Return the schema as read from
-        /// the input file / stream
+        /// Return the schema as read from the file or stream.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>Parse schema from the file or stream.</returns>
         Schema GetSchema();
 
         /// <summary>
-        /// Return the list of keys in the metadata
+        /// Return the list of keys in the metadata.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>Metadata keys from the header of the data file.</returns>
         ICollection<string> GetMetaKeys();
 
         /// <summary>
-        /// Return an enumeration of the remaining entries in the file
+        /// Return an enumeration of the remaining entries in the file.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>An enumeration of the remaining entries in the file.</returns>
         IEnumerable<T> NextEntries { get; }
 
         /// <summary>
         /// Read the next datum from the file.
         /// </summary>
+        /// <returns>Next deserialized data entry.</returns>
         T Next();
 
         /// <summary>
-        /// True if more entries remain in this file.
+        /// Returns true if more entries remain in this file.
         /// </summary>
+        /// <returns>True if more entries remain in this file, false otherwise.</returns>
         bool HasNext();
 
         /// <summary>
-        /// Return the byte value of a metadata property
+        /// Return the byte value of a metadata property.
         /// </summary>
-        /// <param name="key"></param>
-        /// <returns></returns>
+        /// <param name="key">Key for the metadata entry.</param>
+        /// <returns>Raw bytes of the value of the metadata entry.</returns>
+        /// <exception cref="KeyNotFoundException">
+        /// There is no metadata entry with the specified <paramref name="key"/>.
+        /// </exception>
         byte[] GetMeta(string key);
 
         /// <summary>
-        /// Return the long value of a metadata property
+        /// Return the long value of a metadata property.
         /// </summary>
-        /// <param name="key"></param>
-        /// <returns></returns>
+        /// <param name="key">Key for the metadata entry.</param>
+        /// <returns>Metadata value as a long.</returns>
+        /// <exception cref="KeyNotFoundException">
+        /// There is no metadata entry with the specified <paramref name="key"/>.
+        /// </exception>
         long GetMetaLong(string key);
 
         /// <summary>
-        /// Return the string value of a metadata property
+        /// Return the string value of a metadata property. This method assumes that the string is a
+        /// UTF-8 encoded in the header.
         /// </summary>
-        /// <param name="key"></param>
-        /// <returns></returns>
+        /// <param name="key">Key for the metadata entry.</param>
+        /// <returns>Metadata value as a string.</returns>
+        /// <exception cref="KeyNotFoundException">
+        /// There is no metadata entry with the specified <paramref name="key"/>.
+        /// </exception>
+        /// <exception cref="AvroRuntimeException">
+        /// Encountered an exception while decoding the value as a UTF-8 string.
+        /// </exception>
         string GetMetaString(string key);
 
         /// <summary>
-        /// Return true if past the next synchronization
-        /// point after a position
+        /// Return true if past the next synchronization point after a position.
         /// </summary>
-        /// <param name="position"></param>
-        /// <returns></returns>
+        /// <param name="position">Position to test.</param>
+        /// <returns>
+        /// True if pasth the next synchronization point after <paramref name="position"/>, false
+        /// otherwise.
+        /// </returns>
         bool PastSync(long position);
 
         /// <summary>
-        /// Return the last synchronization point before
-        /// our current position
+        /// Return the last synchronization point before our current position.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>
+        /// Position of the last synchronization point before our current position.
+        /// </returns>
         long PreviousSync();
 
         /// <summary>
         /// Move to a specific, known synchronization point,
-        /// one returned from IFileWriter.Sync() while writing
+        /// one returned from <see cref="IFileWriter{T}.Sync"/> while writing.
         /// </summary>
-        /// <param name="position"></param>
+        /// <param name="position">Position to jump to.</param>
         void Seek(long position);
 
         /// <summary>
-        /// Move to the next synchronization point
-        /// after a position
+        /// Move to the next synchronization point after a position.
         /// </summary>
-        /// <param name="position"></param>
+        /// <param name="position">Position in the stream to start.</param>
         void Sync(long position);
 
         /// <summary>
-        /// Return the current position in the input
+        /// Return the current position in the input.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>Current position in the input.</returns>
         long Tell();
     }
 }
diff --git a/lang/csharp/src/apache/main/File/IFileWriter.cs b/lang/csharp/src/apache/main/File/IFileWriter.cs
index 778e6f3..9e8e522 100644
--- a/lang/csharp/src/apache/main/File/IFileWriter.cs
+++ b/lang/csharp/src/apache/main/File/IFileWriter.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -19,67 +19,75 @@ using System;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Defines the interface for an object that stores in a file a sequence of data conforming to
+    /// a schema.
+    /// </summary>
+    /// <typeparam name="T">Type that we will serialize to the file.</typeparam>
     public interface IFileWriter<T> : IDisposable
     {
         /// <summary>
-        /// Append datum to a file / stream
+        /// Append datum to a file or stream.
         /// </summary>
-        /// <param name="datum"></param>
+        /// <param name="datum">Datum to append.</param>
         void Append(T datum);
 
         /// <summary>
-        /// Closes the file / stream
+        /// Closes the file or stream.
         /// </summary>
         void Close();
 
         /// <summary>
-        /// Flush out any buffered data
+        /// Flush out any buffered data.
         /// </summary>
         void Flush();
 
-        /// Returns true if parameter is a
-        /// reserved Avro meta data value
+        /// <summary>
+        /// Returns true if parameter is a reserved Avro metadata value.
         /// </summary>
-        /// <param name="key"></param>
-        /// <returns></returns>
+        /// <param name="key">Metadata key.</param>
+        /// <returns>
+        /// True if parameter is a reserved Avro metadata value, false otherwise.
+        /// </returns>
         bool IsReservedMeta(string key);
 
         /// <summary>
-        /// Set meta data pair
+        /// Set metadata pair.
         /// </summary>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        void SetMeta(String key, byte[] value);
+        /// <param name="key">Metadata key.</param>
+        /// <param name="value">Metadata value.</param>
+        void SetMeta(string key, byte[] value);
 
         /// <summary>
-        /// Set meta data pair (long value)
+        /// Set metadata pair (long value).
         /// </summary>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        void SetMeta(String key, long value);
+        /// <param name="key">Metadata key.</param>
+        /// <param name="value">Metadata value.</param>
+        void SetMeta(string key, long value);
 
         /// <summary>
-        /// Set meta data pair (string value)
+        /// Set metadata pair (string value).
         /// </summary>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        void SetMeta(String key, string value);
+        /// <param name="key">Metadata key.</param>
+        /// <param name="value">Metadata value.</param>
+        void SetMeta(string key, string value);
 
         /// <summary>
-        /// Set the synchronization interval for this
-        /// file / stream, in bytes. Valid values range
-        /// from 32 to 2^30. Suggested values are
-        /// between 2K and 2M
+        /// Set the synchronization interval for this file or stream, in bytes. Valid values range
+        /// from 32 to 2^30. Suggested values are between 2K and 2M.
         /// </summary>
-        /// <param name="syncInterval"></param>
-        /// <returns></returns>
+        /// <param name="syncInterval">
+        /// Approximate number of uncompressed bytes to write in each block.
+        /// </param>
         void SetSyncInterval(int syncInterval);
 
         /// <summary>
-        /// Forces the end of the current block,
-        /// emitting a synchronization marker
+        /// Forces the end of the current block, emitting a synchronization marker.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>
+        /// Current position as a value that may be passed to
+        /// <see cref="IFileReader{T}.Seek(long)"/>.
+        /// </returns>
         long Sync();
     }
 }
diff --git a/lang/csharp/src/apache/main/File/NullCodec.cs b/lang/csharp/src/apache/main/File/NullCodec.cs
index c45f3e6..873047d 100644
--- a/lang/csharp/src/apache/main/File/NullCodec.cs
+++ b/lang/csharp/src/apache/main/File/NullCodec.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,32 +15,39 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 
 namespace Avro.File
 {
+    /// <summary>
+    /// Implements a codec that does not perform any compression. This codec simply returns the
+    /// bytes presented to it "as-is".
+    /// </summary>
     public class NullCodec : Codec
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="NullCodec"/> class.
+        /// </summary>
         public NullCodec() { }
 
+        /// <inheritdoc/>
         public override byte[] Compress(byte[] uncompressedData)
         {
             return uncompressedData;
         }
 
+        /// <inheritdoc/>
         public override byte[] Decompress(byte[] compressedData)
         {
             return compressedData;
         }
 
+        /// <inheritdoc/>
         public override string GetName()
         {
             return DataFileConstants.NullCodec;
         }
 
+        /// <inheritdoc/>
         public override bool Equals(object other)
         {
             if (this == other)
@@ -48,6 +55,7 @@ namespace Avro.File
             return (this.GetType().Name == other.GetType().Name);
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             return DataFileConstants.NullCodecHash;
diff --git a/lang/csharp/src/apache/main/Generic/DatumReader.cs b/lang/csharp/src/apache/main/Generic/DatumReader.cs
index 07370a4..e1f4213 100644
--- a/lang/csharp/src/apache/main/Generic/DatumReader.cs
+++ b/lang/csharp/src/apache/main/Generic/DatumReader.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,15 +15,24 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
 using Avro.IO;
 
 namespace Avro.Generic
 {
+    /// <summary>
+    /// Defines the interface for an object that reads data of a schema.
+    /// </summary>
+    /// <typeparam name="T">Type of the in-memory data representation.</typeparam>
     public interface DatumReader<T>
     {
+        /// <summary>
+        /// Schema used to read the data.
+        /// </summary>
         Schema ReaderSchema { get; }
+
+        /// <summary>
+        /// Schema that was used to write the data.
+        /// </summary>
         Schema WriterSchema { get; }
 
         /// <summary>
@@ -31,6 +40,9 @@ namespace Avro.Generic
         /// in the schema into a datum that is returned.  If the provided datum is
         /// non-null it may be reused and returned.
         /// </summary>
+        /// <param name="reuse">Optional object to deserialize the datum into. May be null.</param>
+        /// <param name="decoder">Decoder to read data from.</param>
+        /// <returns>Deserialized datum.</returns>
         T Read(T reuse, Decoder decoder);
     }
 }
diff --git a/lang/csharp/src/apache/main/Generic/DatumWriter.cs b/lang/csharp/src/apache/main/Generic/DatumWriter.cs
index 5df6f3b..dcf7993 100644
--- a/lang/csharp/src/apache/main/Generic/DatumWriter.cs
+++ b/lang/csharp/src/apache/main/Generic/DatumWriter.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,14 +15,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
 using Avro.IO;
 
 namespace Avro.Generic
 {
+    /// <summary>
+    /// Defines the interface for an object that writes data of a schema.
+    /// </summary>
+    /// <typeparam name="T">Type of the in-memory data representation.</typeparam>
     public interface DatumWriter<T>
     {
+        /// <summary>
+        /// Schema used to write the data.
+        /// </summary>
         Schema Schema { get; }
+
+        /// <summary>
+        /// Write a datum. Traverse the schema, depth first, writing each leaf value in the schema
+        /// from the datum to the output.
+        /// </summary>
+        /// <param name="datum">Datum to write</param>
+        /// <param name="encoder">Encoder to write to</param>
         void Write(T datum, Encoder encoder);
     }
 }
diff --git a/lang/csharp/src/apache/main/Generic/GenericDatumReader.cs b/lang/csharp/src/apache/main/Generic/GenericDatumReader.cs
index 31d5c3e..199453a 100644
--- a/lang/csharp/src/apache/main/Generic/GenericDatumReader.cs
+++ b/lang/csharp/src/apache/main/Generic/GenericDatumReader.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -25,10 +25,16 @@ namespace Avro.Generic
     /// <see cref="PreresolvingDatumReader{T}">For more information about performance considerations for choosing this implementation</see>
     public class GenericDatumReader<T> : PreresolvingDatumReader<T>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericDatumReader{T}"/> class.
+        /// </summary>
+        /// <param name="writerSchema">Schema that was used to write the data.</param>
+        /// <param name="readerSchema">Schema to use to read the data.</param>
         public GenericDatumReader(Schema writerSchema, Schema readerSchema) : base(writerSchema, readerSchema)
         {
         }
 
+        /// <inheritdoc/>
         protected override bool IsReusable(Schema.Type tag)
         {
             switch (tag)
@@ -46,26 +52,31 @@ namespace Avro.Generic
             return true;
         }
 
+        /// <inheritdoc/>
         protected override ArrayAccess GetArrayAccess(ArraySchema readerSchema)
         {
             return new GenericArrayAccess();
         }
 
+        /// <inheritdoc/>
         protected override EnumAccess GetEnumAccess(EnumSchema readerSchema)
         {
             return new GenericEnumAccess(readerSchema);
         }
 
+        /// <inheritdoc/>
         protected override MapAccess GetMapAccess(MapSchema readerSchema)
         {
             return new GenericMapAccess();
         }
 
+        /// <inheritdoc/>
         protected override RecordAccess GetRecordAccess(RecordSchema readerSchema)
         {
             return new GenericRecordAccess(readerSchema);
         }
 
+        /// <inheritdoc/>
         protected override FixedAccess GetFixedAccess(FixedSchema readerSchema)
         {
             return new GenericFixedAccess(readerSchema);
@@ -208,4 +219,4 @@ namespace Avro.Generic
             }
         }
     }
-}
\ No newline at end of file
+}
diff --git a/lang/csharp/src/apache/main/Generic/GenericDatumWriter.cs b/lang/csharp/src/apache/main/Generic/GenericDatumWriter.cs
index ab5d80c..94100bf 100644
--- a/lang/csharp/src/apache/main/Generic/GenericDatumWriter.cs
+++ b/lang/csharp/src/apache/main/Generic/GenericDatumWriter.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -27,10 +27,16 @@ namespace Avro.Generic
     /// </summary>
     public class GenericDatumWriter<T> : PreresolvingDatumWriter<T>
     {
-        public GenericDatumWriter( Schema schema ) : base(schema, new GenericArrayAccess(), new DictionaryMapAccess())
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericDatumWriter{T}"/> class.
+        /// </summary>
+        /// <param name="schema">Schema this writer will use.</param>
+        public GenericDatumWriter(Schema schema)
+            : base(schema, new GenericArrayAccess(), new DictionaryMapAccess())
         {
         }
 
+        /// <inheritdoc/>
         protected override void WriteRecordFields(object recordObj, RecordFieldWriter[] writers, Encoder encoder)
         {
             var record = (GenericRecord) recordObj;
@@ -40,6 +46,7 @@ namespace Avro.Generic
             }
         }
 
+        /// <inheritdoc/>
         protected override void EnsureRecordObject( RecordSchema recordSchema, object value )
         {
             if( value == null || !( value is GenericRecord ) || !( ( value as GenericRecord ).Schema.Equals( recordSchema ) ) )
@@ -48,11 +55,13 @@ namespace Avro.Generic
             }
         }
 
+        /// <inheritdoc/>
         protected override void WriteField(object record, string fieldName, int fieldPos, WriteItem writer, Encoder encoder)
         {
             writer(((GenericRecord)record)[fieldName], encoder);
         }
 
+        /// <inheritdoc/>
         protected override WriteItem ResolveEnum(EnumSchema es)
         {
             return (v,e) =>
@@ -63,6 +72,7 @@ namespace Avro.Generic
                        };
         }
 
+        /// <inheritdoc/>
         protected override void WriteFixed( FixedSchema es, object value, Encoder encoder )
         {
             if (value == null || !(value is GenericFixed) || !(value as GenericFixed).Schema.Equals(es))
@@ -73,12 +83,18 @@ namespace Avro.Generic
             encoder.WriteFixed(ba.Value);
         }
 
-        /*
-         * FIXME: This method of determining the Union branch has problems. If the data is IDictionary<string, object>
-         * if there are two branches one with record schema and the other with map, it choose the first one. Similarly if
-         * the data is byte[] and there are fixed and bytes schemas as branches, it choose the first one that matches.
-         * Also it does not recognize the arrays of primitive types.
-         */
+        /// <summary>
+        /// Tests whether the given schema an object are compatible.
+        /// </summary>
+        /// <remarks>
+        /// FIXME: This method of determining the Union branch has problems. If the data is IDictionary&lt;string, object&gt;
+        /// if there are two branches one with record schema and the other with map, it choose the first one. Similarly if
+        /// the data is byte[] and there are fixed and bytes schemas as branches, it choose the first one that matches.
+        /// Also it does not recognize the arrays of primitive types.
+        /// </remarks>
+        /// <param name="sc">Schema to compare</param>
+        /// <param name="obj">Object to compare</param>
+        /// <returns>True if the two parameters are compatible, false otherwise.</returns>
         protected override bool UnionBranchMatches(Schema sc, object obj)
         {
             if (obj == null && sc.Tag != Avro.Schema.Type.Null) return false;
diff --git a/lang/csharp/src/apache/main/Generic/GenericEnum.cs b/lang/csharp/src/apache/main/Generic/GenericEnum.cs
index 4e0cfbc..d80ecff 100644
--- a/lang/csharp/src/apache/main/Generic/GenericEnum.cs
+++ b/lang/csharp/src/apache/main/Generic/GenericEnum.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,19 +15,24 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Avro.Generic
 {
     /// <summary>
-    /// The defualt class to hold values for enum schema in GenericReader and GenericWriter.
+    /// The default class to hold values for enum schema in GenericReader and GenericWriter.
     /// </summary>
     public class GenericEnum
     {
+        /// <summary>
+        /// Schema for this enum.
+        /// </summary>
         public EnumSchema Schema { get; private set; }
+
         private string value;
+
+        /// <summary>
+        /// Value of the enum.
+        /// </summary>
         public string Value {
             get { return value; }
             set
@@ -37,27 +42,34 @@ namespace Avro.Generic
             }
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericEnum"/> class.
+        /// </summary>
+        /// <param name="schema">Schema for this enum.</param>
+        /// <param name="value">Value of the enum.</param>
         public GenericEnum(EnumSchema schema, string value)
         {
             this.Schema = schema;
             this.Value = value;
         }
 
+        /// <inheritdoc/>
         public override bool Equals(object obj)
         {
             if (obj == this) return true;
             return (obj != null && obj is GenericEnum) ? Value.Equals((obj as GenericEnum).Value) : false;
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             return 17 * Value.GetHashCode();
         }
 
+        /// <inheritdoc/>
         public override string ToString()
         {
             return "Schema: " + Schema + ", value: " + Value;
         }
-
     }
 }
diff --git a/lang/csharp/src/apache/main/Generic/GenericFixed.cs b/lang/csharp/src/apache/main/Generic/GenericFixed.cs
index c0ab443..021f510 100644
--- a/lang/csharp/src/apache/main/Generic/GenericFixed.cs
+++ b/lang/csharp/src/apache/main/Generic/GenericFixed.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -16,9 +16,6 @@
  * limitations under the License.
  */
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 
 namespace Avro.Generic
 {
@@ -27,9 +24,15 @@ namespace Avro.Generic
     /// </summary>
     public class GenericFixed
     {
+        /// <summary>
+        /// Value of this fixed.
+        /// </summary>
         protected readonly byte[] value;
         private FixedSchema schema;
 
+        /// <summary>
+        /// Schema for this fixed.
+        /// </summary>
         public FixedSchema Schema
         {
             get
@@ -49,12 +52,21 @@ namespace Avro.Generic
             }
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericFixed"/> class.
+        /// </summary>
+        /// <param name="schema">Schema for this fixed.</param>
         public GenericFixed(FixedSchema schema)
         {
             value = new byte[schema.Size];
             this.Schema = schema;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericFixed"/> class with a value.
+        /// </summary>
+        /// <param name="schema">Schema for this fixed.</param>
+        /// <param name="value">Value of the fixed.</param>
         public GenericFixed(FixedSchema schema, byte[] value)
         {
             this.value = new byte[schema.Size];
@@ -62,11 +74,18 @@ namespace Avro.Generic
             Value = value;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericFixed"/> class with a size.
+        /// </summary>
+        /// <param name="size">Size of the fixed in bytes.</param>
         protected GenericFixed(uint size)
         {
             this.value = new byte[size];
         }
 
+        /// <summary>
+        /// Value of this fixed.
+        /// </summary>
         public byte[] Value
         {
             get { return this.value; }
@@ -81,6 +100,7 @@ namespace Avro.Generic
             }
         }
 
+        /// <inheritdoc/>
         public override bool Equals(object obj)
         {
             if (this == obj) return true;
@@ -96,6 +116,7 @@ namespace Avro.Generic
             return false;
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             int result = Schema.GetHashCode();
diff --git a/lang/csharp/src/apache/main/Generic/GenericReader.cs b/lang/csharp/src/apache/main/Generic/GenericReader.cs
index 02d8e54..9c1a25e 100644
--- a/lang/csharp/src/apache/main/Generic/GenericReader.cs
+++ b/lang/csharp/src/apache/main/Generic/GenericReader.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -22,6 +22,11 @@ using System.IO;
 
 namespace Avro.Generic
 {
+    /// <summary>
+    /// A function that can read the Avro type from the stream.
+    /// </summary>
+    /// <typeparam name="T">Type to read.</typeparam>
+    /// <returns>The read object.</returns>
     public delegate T Reader<T>();
 
     /// <summary>
@@ -56,10 +61,24 @@ namespace Avro.Generic
             this.reader = reader;
         }
 
+        /// <summary>
+        /// Schema used to write the data.
+        /// </summary>
         public Schema WriterSchema { get { return reader.WriterSchema; } }
 
+        /// <summary>
+        /// Schema used to read the data.
+        /// </summary>
         public Schema ReaderSchema { get { return reader.ReaderSchema; } }
 
+        /// <summary>
+        /// Reads an object off the stream.
+        /// </summary>
+        /// <param name="reuse">
+        /// If not null, the implemenation will try to use to return the object
+        /// </param>
+        /// <param name="d">Decoder to read from.</param>
+        /// <returns>Object we read from the decoder.</returns>
         public T Read(T reuse, Decoder d)
         {
             return reader.Read(reuse, d);
@@ -80,7 +99,14 @@ namespace Avro.Generic
     /// </remarks>
     public class DefaultReader
     {
+        /// <summary>
+        /// Schema to use when reading data with this reader.
+        /// </summary>
         public Schema ReaderSchema { get; private set; }
+
+        /// <summary>
+        /// Schema used to write data that we are reading with this reader.
+        /// </summary>
         public Schema WriterSchema { get; private set; }
 
 
@@ -105,7 +131,7 @@ namespace Avro.Generic
         /// </typeparam>
         /// <param name="reuse">If not null, the implemenation will try to use to return the object</param>
         /// <param name="decoder">The decoder for deserialization</param>
-        /// <returns></returns>
+        /// <returns>Object read from the decoder.</returns>
         public T Read<T>(T reuse, Decoder decoder)
         {
             if (!ReaderSchema.CanRead(WriterSchema))
@@ -114,6 +140,16 @@ namespace Avro.Generic
             return (T)Read(reuse, WriterSchema, ReaderSchema, decoder);
         }
 
+        /// <summary>
+        /// Reads an object off the stream.
+        /// </summary>
+        /// <param name="reuse">
+        /// If not null, the implemenation will try to use to return the object.
+        /// </param>
+        /// <param name="writerSchema">Schema used to write the data.</param>
+        /// <param name="readerSchema">Schema to use when reading the data.</param>
+        /// <param name="d">Decoder to read from.</param>
+        /// <returns>Object read from the decoder.</returns>
         public object Read(object reuse, Schema writerSchema, Schema readerSchema, Decoder d)
         {
             if (readerSchema.Tag == Schema.Type.Union && writerSchema.Tag != Schema.Type.Union)
@@ -294,6 +330,7 @@ namespace Avro.Generic
         /// <param name="record">The record object to be probed into. This is guaranteed to be one that was returned
         /// by a previous call to CreateRecord.</param>
         /// <param name="fieldName">The name of the field to probe.</param>
+        /// <param name="fieldPos">Position of the field in the schema - not used in the base implementation.</param>
         /// <param name="value">The value of the field, if found. Null otherwise.</param>
         /// <returns>True if and only if a field with the given name is found.</returns>
         protected virtual bool TryGetField(object record, string fieldName, int fieldPos, out object value)
@@ -308,6 +345,7 @@ namespace Avro.Generic
         /// <param name="record">The record object to be probed into. This is guaranteed to be one that was returned
         /// by a previous call to CreateRecord.</param>
         /// <param name="fieldName">The name of the field to probe.</param>
+        /// <param name="fieldPos">Position of the field in the schema - not used in the base implementation.</param>
         /// <param name="fieldValue">The value to be added for the field</param>
         protected virtual void AddField(object record, string fieldName, int fieldPos, object fieldValue)
         {
@@ -381,6 +419,7 @@ namespace Avro.Generic
         /// should use GetArraySize() to determine the size. The default implementation creates an <c>object[]</c>.
         /// </summary>
         /// <param name="reuse">If appropriate use this instead of creating a new one.</param>
+        /// <param name="rs">Array schema, not used in base implementation</param>
         /// <returns>An object suitable to deserialize an avro array</returns>
         protected virtual object CreateArray(object reuse, ArraySchema rs)
         {
@@ -462,9 +501,10 @@ namespace Avro.Generic
 
         /// <summary>
         /// Used by the default implementation of ReadMap() to create a fresh map object. The default
-        /// implementaion of this method returns a IDictionary<string, map>.
+        /// implementaion of this method returns a IDictionary&lt;string, map&gt;.
         /// </summary>
         /// <param name="reuse">If appropriate, use this map object instead of creating a new one.</param>
+        /// <param name="ms">Map schema to use when creating the object.</param>
         /// <returns>An empty map object.</returns>
         protected virtual object CreateMap(object reuse, MapSchema ms)
         {
@@ -558,6 +598,11 @@ namespace Avro.Generic
             return (f as GenericFixed).Value;
         }
 
+        /// <summary>
+        /// Skip an instance of a schema.
+        /// </summary>
+        /// <param name="writerSchema">Schema to skip.</param>
+        /// <param name="d">Decoder we're reading from.</param>
         protected virtual void Skip(Schema writerSchema, Decoder d)
         {
             switch (writerSchema.Tag)
@@ -621,6 +666,12 @@ namespace Avro.Generic
             }
         }
 
+        /// <summary>
+        /// Finds the branch of the union schema associated with the given schema.
+        /// </summary>
+        /// <param name="us">Union schema.</param>
+        /// <param name="s">Schema to find in the union schema.</param>
+        /// <returns>Schema branch in the union schema.</returns>
         protected static Schema findBranch(UnionSchema us, Schema s)
         {
             int index = us.MatchingBranch(s);
diff --git a/lang/csharp/src/apache/main/Generic/GenericRecord.cs b/lang/csharp/src/apache/main/Generic/GenericRecord.cs
index 02e1e04..a96280f 100644
--- a/lang/csharp/src/apache/main/Generic/GenericRecord.cs
+++ b/lang/csharp/src/apache/main/Generic/GenericRecord.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -27,19 +27,48 @@ namespace Avro.Generic
     /// </summary>
     public class GenericRecord : IEquatable<GenericRecord>
     {
+        /// <summary>
+        /// Schema for this record.
+        /// </summary>
         public RecordSchema Schema { get; private set; }
 
         private readonly Dictionary<string, object> contents = new Dictionary<string, object>();
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericRecord"/> class.
+        /// </summary>
+        /// <param name="schema">Schema for this record.</param>
         public GenericRecord(RecordSchema schema)
         {
             this.Schema = schema;
         }
 
+        /// <summary>
+        /// Returns the value of the field with the given name.
+        /// </summary>
+        /// <param name="fieldName">Name of the field.</param>
+        /// <returns>Value of the field with the given name.</returns>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="fieldName"/> is null.
+        /// </exception>
+        /// <exception cref="KeyNotFoundException">
+        /// <paramref name="fieldName"/> does not exist in this record.
+        /// </exception>
         public object this[string fieldName]
         {
             get { return contents[fieldName]; }
         }
 
+        /// <summary>
+        /// Sets the value for a field. You may call this method multiple times with the same
+        /// field name to change its value. The given field name must exist in the schema. This
+        /// method does not ensure that the given field value is compatible with the field's schema.
+        /// </summary>
+        /// <param name="fieldName">Name of the field.</param>
+        /// <param name="fieldValue">Value of the field.</param>
+        /// <exception cref="AvroException">
+        /// <paramref name="fieldName"/> does not exist in this record.
+        /// </exception>
         public void Add(string fieldName, object fieldValue)
         {
             if (Schema.Contains(fieldName))
@@ -52,11 +81,25 @@ namespace Avro.Generic
             throw new AvroException("No such field: " + fieldName);
         }
 
+        /// <summary>
+        /// Gets the value the specified field name.
+        /// </summary>
+        /// <param name="fieldName">Name of the field.</param>
+        /// <param name="result">
+        /// When this method returns true, contains the value of the specified field;
+        /// otherwise, null.
+        /// </param>
+        /// <returns>
+        /// True if the field was found in the record. This method will only return true if
+        /// <see cref="Add(string, object)"/> has been called for the given field name. This method
+        /// cannot be used to determine whether or not the schema has a field with a given name.
+        /// </returns>
         public bool TryGetValue(string fieldName, out object result)
         {
             return contents.TryGetValue(fieldName, out result);
         }
 
+        /// <inheritdoc/>
         public override bool Equals(object obj)
         {
             if (this == obj) return true;
@@ -64,6 +107,7 @@ namespace Avro.Generic
                 && Equals((GenericRecord)obj);
         }
 
+        /// <inheritdoc/>
         public bool Equals(GenericRecord other)
         {
             return Schema.Equals(other.Schema)
@@ -113,11 +157,13 @@ namespace Avro.Generic
             return true;
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             return 31 * contents.GetHashCode()/* + 29 * Schema.GetHashCode()*/;
         }
 
+        /// <inheritdoc/>
         public override string ToString()
         {
             StringBuilder sb = new StringBuilder();
diff --git a/lang/csharp/src/apache/main/Generic/GenericWriter.cs b/lang/csharp/src/apache/main/Generic/GenericWriter.cs
index 3d2ef6f..7a08b68 100644
--- a/lang/csharp/src/apache/main/Generic/GenericWriter.cs
+++ b/lang/csharp/src/apache/main/Generic/GenericWriter.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -21,7 +21,13 @@ using Avro.IO;
 
 namespace Avro.Generic
 {
+    /// <summary>
+    /// Defines the signature for a function that writes an object.
+    /// </summary>
+    /// <typeparam name="T">Type of object to write.</typeparam>
+    /// <param name="t">Object to write.</param>
     public delegate void Writer<T>(T t);
+
     /// <summary>
     /// A typesafe wrapper around DefaultWriter. While a specific object of DefaultWriter
     /// allows the client to serialize a generic type, an object of this class allows
@@ -31,13 +37,24 @@ namespace Avro.Generic
     public class GenericWriter<T> : DatumWriter<T>
     {
         private readonly DefaultWriter writer;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericWriter{T}"/> class.
+        /// </summary>
+        /// <param name="schema">Schema to use when writing.</param>
         public GenericWriter(Schema schema) : this(new DefaultWriter(schema))
         {
 
         }
 
+        /// <inheritdoc/>
         public Schema Schema { get { return writer.Schema; } }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GenericWriter{T}"/> class from a
+        /// <see cref="DefaultWriter"/>.
+        /// </summary>
+        /// <param name="writer">Write to initialize this new writer from.</param>
         public GenericWriter(DefaultWriter writer)
         {
             this.writer = writer;
@@ -62,6 +79,9 @@ namespace Avro.Generic
     /// </summary>
     public class DefaultWriter
     {
+        /// <summary>
+        /// Schema that this object uses to write datum.
+        /// </summary>
         public Schema Schema { get; private set; }
 
         /// <summary>
@@ -70,13 +90,21 @@ namespace Avro.Generic
         /// <param name="schema">The schema for the object to be serialized</param>
         public DefaultWriter(Schema schema)
         {
-            this.Schema = schema;
+            Schema = schema;
         }
 
+        /// <summary>
+        /// Examines the <see cref="Schema"/> and dispatches the actual work to one
+        /// of the other methods of this class. This allows the derived
+        /// classes to override specific methods and get custom results.
+        /// </summary>
+        /// <param name="value">The value to be serialized</param>
+        /// <param name="encoder">The encoder to use during serialization</param>
         public void Write<T>(T value, Encoder encoder)
         {
             Write(Schema, value, encoder);
         }
+
         /// <summary>
         /// Examines the schema and dispatches the actual work to one
         /// of the other methods of this class. This allows the derived
@@ -133,7 +161,7 @@ namespace Avro.Generic
                     WriteUnion(schema as UnionSchema, value, encoder);
                     break;
                 default:
-                    error(schema, value);
+                    Error(schema, value);
                     break;
             }
         }
@@ -186,6 +214,12 @@ namespace Avro.Generic
             }
         }
 
+        /// <summary>
+        /// Ensures that the given value is a record and that it corresponds to the given schema.
+        /// Throws an exception if either of those assertions are false.
+        /// </summary>
+        /// <param name="s">Schema associated with the record</param>
+        /// <param name="value">Ensure this object is a record</param>
         protected virtual void EnsureRecordObject(RecordSchema s, object value)
         {
             if (value == null || !(value is GenericRecord) || !((value as GenericRecord).Schema.Equals(s)))
@@ -305,7 +339,7 @@ namespace Avro.Generic
 
         /// <summary>
         /// Checks if the given object is a map. If it is a valid map, this function returns normally. Otherwise,
-        /// it throws an exception. The default implementation checks if the value is an IDictionary<string, object>.
+        /// it throws an exception. The default implementation checks if the value is an IDictionary&lt;string, object&gt;.
         /// </summary>
         /// <param name="value"></param>
         protected virtual void EnsureMapObject(object value)
@@ -316,7 +350,7 @@ namespace Avro.Generic
         /// <summary>
         /// Returns the size of the map object. The default implementation gurantees that EnsureMapObject has been
         /// successfully called with the given value. The default implementation requires the value
-        /// to be an IDictionary<string, object> and returns the number of elements in it.
+        /// to be an IDictionary&lt;string, object&gt; and returns the number of elements in it.
         /// </summary>
         /// <param name="value">The map object whose size is desired</param>
         /// <returns>The size of the given map object</returns>
@@ -328,7 +362,7 @@ namespace Avro.Generic
         /// <summary>
         /// Returns the contents of the given map object. The default implementation guarantees that EnsureMapObject
         /// has been called with the given value. The defualt implementation of this method requires that
-        /// the value is an IDictionary<string, object> and returns its contents.
+        /// the value is an IDictionary&lt;string, object&gt; and returns its contents.
         /// </summary>
         /// <param name="value">The map object whose size is desired</param>
         /// <returns>The contents of the given map object</returns>
@@ -386,22 +420,36 @@ namespace Avro.Generic
             encoder.WriteFixed(ba.Value);
         }
 
+        /// <summary>
+        /// Creates a new <see cref="AvroException"/> and uses the provided parameters to build an
+        /// exception message indicathing there was a type mismatch.
+        /// </summary>
+        /// <param name="obj">Object whose type does not the expected type</param>
+        /// <param name="schemaType">Schema that we tried to write against</param>
+        /// <param name="type">Type that we expected</param>
+        /// <returns>A new <see cref="AvroException"/> indicating a type mismatch.</returns>
         protected AvroException TypeMismatch(object obj, string schemaType, string type)
         {
             return new AvroException(type + " required to write against " + schemaType + " schema but found " + (null == obj ? "null" : obj.GetType().ToString()) );
         }
 
-        private void error(Schema schema, Object value)
+        private void Error(Schema schema, Object value)
         {
             throw new AvroTypeException("Not a " + schema + ": " + value);
         }
 
-        /*
-         * FIXME: This method of determining the Union branch has problems. If the data is IDictionary<string, object>
-         * if there are two branches one with record schema and the other with map, it choose the first one. Similarly if
-         * the data is byte[] and there are fixed and bytes schemas as branches, it choose the first one that matches.
-         * Also it does not recognize the arrays of primitive types.
-         */
+        /// <summary>
+        /// Tests whether the given schema an object are compatible.
+        /// </summary>
+        /// <remarks>
+        /// FIXME: This method of determining the Union branch has problems. If the data is IDictionary&lt;string, object&gt;
+        /// if there are two branches one with record schema and the other with map, it choose the first one. Similarly if
+        /// the data is byte[] and there are fixed and bytes schemas as branches, it choose the first one that matches.
+        /// Also it does not recognize the arrays of primitive types.
+        /// </remarks>
+        /// <param name="sc">Schema to compare</param>
+        /// <param name="obj">Object to compare</param>
+        /// <returns>True if the two parameters are compatible, false otherwise.</returns>
         protected virtual bool Matches(Schema sc, object obj)
         {
             if (obj == null && sc.Tag != Avro.Schema.Type.Null) return false;
diff --git a/lang/csharp/src/apache/main/Generic/PreresolvingDatumReader.cs b/lang/csharp/src/apache/main/Generic/PreresolvingDatumReader.cs
index f98d6cf..b963618 100644
--- a/lang/csharp/src/apache/main/Generic/PreresolvingDatumReader.cs
+++ b/lang/csharp/src/apache/main/Generic/PreresolvingDatumReader.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -28,9 +28,18 @@ namespace Avro.Generic
     /// </summary>
     public abstract class PreresolvingDatumReader<T> : DatumReader<T>
     {
+        /// <inheritdoc/>
         public Schema ReaderSchema { get; private set; }
+
+        /// <inheritdoc/>
         public Schema WriterSchema { get; private set; }
 
+        /// <summary>
+        /// Defines the signature for a function that reads an item from a decoder.
+        /// </summary>
+        /// <param name="reuse">Optional object to deserialize the datum into. May be null.</param>
+        /// <param name="dec">Decoder to read data from.</param>
+        /// <returns>Deserialized datum.</returns>
         protected delegate object ReadItem(object reuse, Decoder dec);
 
         // read a specific field from a decoder
@@ -43,6 +52,11 @@ namespace Avro.Generic
         private readonly ReadItem _reader;
         private readonly Dictionary<SchemaPair,ReadItem> _recordReaders = new Dictionary<SchemaPair,ReadItem>();
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PreresolvingDatumReader{T}"/> class.
+        /// </summary>
+        /// <param name="writerSchema">Schema that was used to write the data.</param>
+        /// <param name="readerSchema">Schema to use to read the data.</param>
         protected PreresolvingDatumReader(Schema writerSchema, Schema readerSchema)
         {
             ReaderSchema = readerSchema;
@@ -52,15 +66,45 @@ namespace Avro.Generic
             _reader = ResolveReader(writerSchema, readerSchema);
         }
 
+        /// <inheritdoc/>
         public T Read(T reuse, Decoder decoder)
         {
             return (T)_reader(reuse, decoder);
         }
 
+        /// <summary>
+        /// Returns an <see cref="ArrayAccess"/> implementation for the given schema.
+        /// </summary>
+        /// <param name="readerSchema">Schema for the array.</param>
+        /// <returns>An <see cref="ArrayAccess"/> implementation.</returns>
         protected abstract ArrayAccess GetArrayAccess(ArraySchema readerSchema);
+
+        /// <summary>
+        /// Returns an <see cref="EnumAccess"/> implementation for the given schema.
+        /// </summary>
+        /// <param name="readerSchema">Schema for the enum.</param>
+        /// <returns>An <see cref="EnumAccess"/> implementation.</returns>
         protected abstract EnumAccess GetEnumAccess(EnumSchema readerSchema);
+
+        /// <summary>
+        /// Returns a <see cref="MapAccess"/> implementation for the given schema.
+        /// </summary>
+        /// <param name="readerSchema">Schema for the map.</param>
+        /// <returns>A <see cref="MapAccess"/> implementation.</returns>
         protected abstract MapAccess GetMapAccess(MapSchema readerSchema);
+
+        /// <summary>
+        /// Returns a <see cref="RecordAccess"/> implementation for the given schema.
+        /// </summary>
+        /// <param name="readerSchema">Schema for the record.</param>
+        /// <returns>A <see cref="RecordAccess"/> implementation.</returns>
         protected abstract RecordAccess GetRecordAccess(RecordSchema readerSchema);
+
+        /// <summary>
+        /// Returns a <see cref="FixedAccess"/> implementation for the given schema.
+        /// </summary>
+        /// <param name="readerSchema">Schema for the fixed.</param>
+        /// <returns>A <see cref="FixedAccess"/> implementation.</returns>
         protected abstract FixedAccess GetFixedAccess(FixedSchema readerSchema);
 
         /// <summary>
@@ -364,6 +408,12 @@ namespace Avro.Generic
             return fixedrec;
         }
 
+        /// <summary>
+        /// Finds the branch of the union schema associated with the given schema.
+        /// </summary>
+        /// <param name="us">Union schema.</param>
+        /// <param name="s">Schema to find in the union schema.</param>
+        /// <returns>Schema branch in the union schema.</returns>
         protected static Schema FindBranch(UnionSchema us, Schema s)
         {
             int index = us.MatchingBranch(s);
@@ -464,6 +514,9 @@ namespace Avro.Generic
 
         // interfaces to handle details of working with Specific vs Generic objects
 
+        /// <summary>
+        /// Defines the interface for a class that provides access to a record implementation.
+        /// </summary>
         protected interface RecordAccess
         {
             /// <summary>
@@ -496,11 +549,23 @@ namespace Avro.Generic
             void AddField(object record, string fieldName, int fieldPos, object fieldValue);
         }
 
+        /// <summary>
+        /// Defines the interface for a class that provides access to an enum implementation.
+        /// </summary>
         protected interface EnumAccess
         {
+            /// <summary>
+            /// Creates an enum value.
+            /// </summary>
+            /// <param name="reuse">Optional object to reuse as the enum value. May be null.</param>
+            /// <param name="ordinal">Ordinal value of the enum entry.</param>
+            /// <returns>An object representing the enum value.</returns>
             object CreateEnum(object reuse, int ordinal);
         }
 
+        /// <summary>
+        /// Defines the interface for a class that provides access to a fixed implementation.
+        /// </summary>
         protected interface FixedAccess
         {
             /// <summary>
@@ -519,6 +584,9 @@ namespace Avro.Generic
             byte[] GetFixedBuffer(object f);
         }
 
+        /// <summary>
+        /// Defines the interface for a class that provides access to an array implementation.
+        /// </summary>
         protected interface ArrayAccess
         {
             /// <summary>
@@ -545,9 +613,24 @@ namespace Avro.Generic
             /// <param name="targetSize">The new size.</param>
             void Resize(ref object array, int targetSize);
 
+            /// <summary>
+            /// Adds elements to the given array by reading values from the decoder.
+            /// </summary>
+            /// <param name="array">Array to add elements to.</param>
+            /// <param name="elements">Number of elements to add.</param>
+            /// <param name="index">Start adding elements to the array at this index.</param>
+            /// <param name="itemReader">Delegate to read an item from the decoder.</param>
+            /// <param name="decoder">Decoder to read from.</param>
+            /// <param name="reuse">
+            /// True to reuse each element in the array when deserializing. False to create a new
+            /// object for each element.
+            /// </param>
             void AddElements( object array, int elements, int index, ReadItem itemReader, Decoder decoder, bool reuse );
         }
 
+        /// <summary>
+        /// Defines the interface for a class that provides access to a map implementation.
+        /// </summary>
         protected interface MapAccess
         {
             /// <summary>
@@ -557,6 +640,17 @@ namespace Avro.Generic
             /// <returns>An empty map object.</returns>
             object Create(object reuse);
 
+            /// <summary>
+            /// Adds elements to the given map by reading values from the decoder.
+            /// </summary>
+            /// <param name="map">Map to add elements to.</param>
+            /// <param name="elements">Number of elements to add.</param>
+            /// <param name="itemReader">Delegate to read an item from the decoder.</param>
+            /// <param name="decoder">Decoder to read from.</param>
+            /// <param name="reuse">
+            /// True to reuse each element in the map when deserializing. False to create a new
+            /// object for each element.
+            /// </param>
             void AddElements(object map, int elements, ReadItem itemReader, Decoder decoder, bool reuse);
         }
 
diff --git a/lang/csharp/src/apache/main/Generic/PreresolvingDatumWriter.cs b/lang/csharp/src/apache/main/Generic/PreresolvingDatumWriter.cs
index c612edc..247a9ae 100644
--- a/lang/csharp/src/apache/main/Generic/PreresolvingDatumWriter.cs
+++ b/lang/csharp/src/apache/main/Generic/PreresolvingDatumWriter.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -30,9 +30,15 @@ namespace Avro.Generic
     /// </summary>
     public abstract class PreresolvingDatumWriter<T> : DatumWriter<T>
     {
+        /// <inheritdoc/>
         public Schema Schema { get; private set; }
 
-        protected delegate void WriteItem(Object value, Encoder encoder);
+        /// <summary>
+        /// Defines the signature for a method that writes a value to an encoder.
+        /// </summary>
+        /// <param name="value">Value to write</param>
+        /// <param name="encoder">Encoder to write to</param>
+        protected delegate void WriteItem(object value, Encoder encoder);
 
         private readonly WriteItem _writer;
         private readonly ArrayAccess _arrayAccess;
@@ -40,11 +46,18 @@ namespace Avro.Generic
 
         private readonly Dictionary<RecordSchema,WriteItem> _recordWriters = new Dictionary<RecordSchema,WriteItem>();
 
+        /// <inheritdoc/>
         public void Write(T datum, Encoder encoder)
         {
-            _writer( datum, encoder );
+            _writer(datum, encoder);
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PreresolvingDatumWriter{T}"/> class.
+        /// </summary>
+        /// <param name="schema">Schema used by this writer</param>
+        /// <param name="arrayAccess">Object used to access array properties</param>
+        /// <param name="mapAccess">Object used to access map properties</param>
         protected PreresolvingDatumWriter(Schema schema, ArrayAccess arrayAccess, MapAccess mapAccess)
         {
             Schema = schema;
@@ -87,7 +100,7 @@ namespace Avro.Generic
                 case Schema.Type.Union:
                     return ResolveUnion((UnionSchema)schema);
                 default:
-                    return (v, e) => error(schema, v);
+                    return (v, e) => Error(schema, v);
             }
         }
 
@@ -116,10 +129,10 @@ namespace Avro.Generic
 
 
         /// <summary>
-        /// Serialized a record using the given RecordSchema. It uses GetField method
+        /// Serializes a record using the given RecordSchema. It uses GetField method
         /// to extract the field value from the given object.
         /// </summary>
-        /// <param name="schema">The RecordSchema to use for serialization</param>
+        /// <param name="recordSchema">The RecordSchema to use for serialization</param>
         private WriteItem ResolveRecord(RecordSchema recordSchema)
         {
             WriteItem recordResolver;
@@ -146,24 +159,47 @@ namespace Avro.Generic
             return recordResolver;
         }
 
+        /// <summary>
+        /// Writes each field of a record to the encoder.
+        /// </summary>
+        /// <param name="record">Record to write</param>
+        /// <param name="writers">Writers for each field in the record</param>
+        /// <param name="encoder">Encoder to write to</param>
         protected abstract void WriteRecordFields(object record, RecordFieldWriter[] writers, Encoder encoder);
 
-
+        /// <summary>
+        /// Correlates a record field with the writer used to serialize that field.
+        /// </summary>
         protected class RecordFieldWriter
         {
+            /// <summary>
+            /// Delegate used to write the <see cref="Field"/> to an encoder.
+            /// </summary>
             public WriteItem WriteField { get; set; }
+
+            /// <summary>
+            /// Field this object is associated with.
+            /// </summary>
             public Field Field { get; set; }
         }
 
+        /// <summary>
+        /// Ensures that the given value is a record and that it corresponds to the given schema.
+        /// Throws an exception if either of those assertions are false.
+        /// </summary>
+        /// <param name="recordSchema">Schema associated with the record</param>
+        /// <param name="value">Ensure this object is a record</param>
         protected abstract void EnsureRecordObject(RecordSchema recordSchema, object value);
 
         /// <summary>
-        /// Extracts the field value from the given object.
+        /// Writes a field from the <paramref name="record"/> to the <paramref name="encoder"/>
+        /// using the <paramref name="writer"/>.
         /// </summary>
-        /// <param name="value">The record value from which the field needs to be extracted</param>
+        /// <param name="record">The record value from which the field needs to be extracted</param>
         /// <param name="fieldName">The name of the field in the record</param>
         /// <param name="fieldPos">The position of field in the record</param>
-        /// <returns></returns>
+        /// <param name="writer">Used to write the field value to the encoder</param>
+        /// <param name="encoder">Encoder to write to</param>
         protected abstract void WriteField(object record, string fieldName, int fieldPos, WriteItem writer, Encoder encoder );
 
         /// <summary>
@@ -173,13 +209,13 @@ namespace Avro.Generic
         protected abstract WriteItem ResolveEnum(EnumSchema es);
 
         /// <summary>
-        /// Serialized an array. The default implementation calls EnsureArrayObject() to ascertain that the
+        /// Creates a <see cref="WriteItem"/> delegate that serializes an array.
+        /// The default implementation calls EnsureArrayObject() to ascertain that the
         /// given value is an array. It then calls GetArrayLength() and GetArrayElement()
         /// to access the members of the array and then serialize them.
         /// </summary>
         /// <param name="schema">The ArraySchema for serialization</param>
-        /// <param name="value">The value being serialized</param>
-        /// <param name="encoder">The encoder for serialization</param>
+        /// <returns>A <see cref="WriteItem"/> that serializes an array.</returns>
         protected WriteItem ResolveArray(ArraySchema schema)
         {
             var itemWriter = ResolveWriter(schema.ItemSchema);
@@ -203,10 +239,10 @@ namespace Avro.Generic
         }
 
         /// <summary>
-        /// Serialized a map. The default implementation first ensure that the value is indeed a map and then uses
+        /// Serializes a map. The default implementation first ensure that the value is indeed a map and then uses
         /// GetMapSize() and GetMapElements() to access the contents of the map.
         /// </summary>
-        /// <param name="schema">The MapSchema for serialization</param>
+        /// <param name="itemWriter">Delegate used to write each map item.</param>
         /// <param name="value">The value to be serialized</param>
         /// <param name="encoder">The encoder for serialization</param>
         protected void WriteMap(WriteItem itemWriter, object value, Encoder encoder)
@@ -237,7 +273,9 @@ namespace Avro.Generic
         /// Resolves the given value against the given UnionSchema and serializes the object against
         /// the resolved schema member.
         /// </summary>
-        /// <param name="us">The UnionSchema to resolve against</param>
+        /// <param name="unionSchema">The UnionSchema to resolve against</param>
+        /// <param name="branchSchemas">Schemas for each type in the union</param>
+        /// <param name="branchWriters">Writers for each type in the union</param>
         /// <param name="value">The value to be serialized</param>
         /// <param name="encoder">The encoder for serialization</param>
         private void WriteUnion(UnionSchema unionSchema, Schema[] branchSchemas, WriteItem[] branchWriters, object value, Encoder encoder)
@@ -253,8 +291,14 @@ namespace Avro.Generic
         /// an exception.
         /// </summary>
         /// <param name="us">The UnionSchema to resolve against</param>
+        /// <param name="branchSchemas">Schemas for types within the union</param>
         /// <param name="obj">The object that should be used in matching</param>
-        /// <returns></returns>
+        /// <returns>
+        /// Index of the schema in <paramref name="branchSchemas"/> that matches the <paramref name="obj"/>.
+        /// </returns>
+        /// <exception cref="AvroException">
+        /// No match found for the object in the union schema.
+        /// </exception>
         protected int ResolveUnion(UnionSchema us, Schema[] branchSchemas, object obj)
         {
             for (int i = 0; i < branchSchemas.Length; i++)
@@ -273,23 +317,48 @@ namespace Avro.Generic
         /// <param name="encoder">The encoder for serialization</param>
         protected abstract void WriteFixed(FixedSchema es, object value, Encoder encoder);
 
+        /// <summary>
+        /// Creates a new <see cref="AvroException"/> and uses the provided parameters to build an
+        /// exception message indicathing there was a type mismatch.
+        /// </summary>
+        /// <param name="obj">Object whose type does not the expected type</param>
+        /// <param name="schemaType">Schema that we tried to write against</param>
+        /// <param name="type">Type that we expected</param>
+        /// <returns>A new <see cref="AvroException"/> indicating a type mismatch.</returns>
         protected static AvroException TypeMismatch(object obj, string schemaType, string type)
         {
             return new AvroException(type + " required to write against " + schemaType + " schema but found " + (null == obj ? "null" : obj.GetType().ToString()) );
         }
 
-        private void error(Schema schema, Object value)
+        private void Error(Schema schema, Object value)
         {
             throw new AvroTypeException("Not a " + schema + ": " + value);
         }
 
+        /// <summary>
+        /// Tests whether the given schema an object are compatible.
+        /// </summary>
+        /// <param name="sc">Schema to compare</param>
+        /// <param name="obj">Object to compare</param>
+        /// <returns>True if the two parameters are compatible, false otherwise.</returns>
         protected abstract bool UnionBranchMatches(Schema sc, object obj);
 
+        /// <summary>
+        /// Obsolete - This will be removed from the public API in a future version.
+        /// </summary>
+        [Obsolete("This will be removed from the public API in a future version.")]
         protected interface EnumAccess
         {
+            /// <summary>
+            /// Obsolete - This will be removed from the public API in a future version.
+            /// </summary>
+            [Obsolete("This will be removed from the public API in a future version.")]
             void WriteEnum(object value);
         }
 
+        /// <summary>
+        /// Defines the interface for a class that provides access to an array implementation.
+        /// </summary>
         protected interface ArrayAccess
         {
             /// <summary>
@@ -310,57 +379,70 @@ namespace Avro.Generic
             long GetArrayLength(object value);
 
             /// <summary>
-            /// Returns the element at the given index from the given array object. The default implementation
-            /// requires that the value is an object array and returns the element in that array. The defaul implementation
-            /// gurantees that EnsureArrayObject() has been called on the value before this
-            /// function is called.
+            /// Writes each value in the given array to the <paramref name="encoder"/> using the
+            /// <paramref name="valueWriter"/>. The default implementation of this method requires
+            /// that the <paramref name="array"/> is an object array.
             /// </summary>
-            /// <param name="value">The array object</param>
-            /// <param name="index">The index to look for</param>
-            /// <returns>The array element at the index</returns>
+            /// <param name="array">The array object</param>
+            /// <param name="valueWriter">Value writer to send the array to.</param>
+            /// <param name="encoder">Encoder to the write the array values to.</param>
             void WriteArrayValues(object array, WriteItem valueWriter, Encoder encoder);
         }
 
+        /// <summary>
+        /// Defines the interface for a class that provides access to a map implementation.
+        /// </summary>
+        /// <seealso cref="DictionaryMapAccess"/>
         protected interface MapAccess
         {
             /// <summary>
             /// Checks if the given object is a map. If it is a valid map, this function returns normally. Otherwise,
-            /// it throws an exception. The default implementation checks if the value is an IDictionary<string, object>.
+            /// it throws an exception. The default implementation checks if the value is an IDictionary&lt;string, object&gt;.
             /// </summary>
-            /// <param name="value"></param>
+            /// <param name="value">Ensures that this object is a valid map.</param>
             void EnsureMapObject(object value);
 
             /// <summary>
             /// Returns the size of the map object. The default implementation gurantees that EnsureMapObject has been
             /// successfully called with the given value. The default implementation requires the value
-            /// to be an IDictionary<string, object> and returns the number of elements in it.
+            /// to be an IDictionary&lt;string, object&gt; and returns the number of elements in it.
             /// </summary>
             /// <param name="value">The map object whose size is desired</param>
             /// <returns>The size of the given map object</returns>
             long GetMapSize(object value);
 
             /// <summary>
-            /// Returns the contents of the given map object. The default implementation guarantees that EnsureMapObject
-            /// has been called with the given value. The defualt implementation of this method requires that
-            /// the value is an IDictionary<string, object> and returns its contents.
+            /// Writes each value in the given map to the <paramref name="encoder"/> using the
+            /// <paramref name="valueWriter"/>. The default implementation of this method requires
+            /// that the <paramref name="map"/> is an IDictionary&lt;string, object&gt;.
             /// </summary>
-            /// <param name="value">The map object whose size is desired</param>
-            /// <returns>The contents of the given map object</returns>
+            /// <param name="map">Map object to write the contents of.</param>
+            /// <param name="valueWriter">Value writer to send the map to.</param>
+            /// <param name="encoder">Encoder to the write the map values to.</param>
             void WriteMapValues(object map, WriteItem valueWriter, Encoder encoder);
         }
 
+        /// <summary>
+        /// Provides access to map properties from an <see cref="IDictionary"/>.
+        /// </summary>
         protected class DictionaryMapAccess : MapAccess
         {
-            public void EnsureMapObject( object value )
+            /// <inheritdoc/>
+            public void EnsureMapObject(object value)
             {
-                if( value == null || !( value is IDictionary ) ) throw TypeMismatch( value, "map", "IDictionary" );
+                if (value as IDictionary == null)
+                {
+                    throw TypeMismatch( value, "map", "IDictionary" );
+                }
             }
 
-            public long GetMapSize( object value )
+            /// <inheritdoc/>
+            public long GetMapSize(object value)
             {
-                return ( (IDictionary) value ).Count;
+                return ((IDictionary) value).Count;
             }
 
+            /// <inheritdoc/>
             public void WriteMapValues(object map, WriteItem valueWriter, Encoder encoder)
             {
                 foreach (DictionaryEntry entry in ((IDictionary)map))
diff --git a/lang/csharp/src/apache/main/IO/BinaryDecoder.cs b/lang/csharp/src/apache/main/IO/BinaryDecoder.cs
index 569c10f..afa59ca 100644
--- a/lang/csharp/src/apache/main/IO/BinaryDecoder.cs
+++ b/lang/csharp/src/apache/main/IO/BinaryDecoder.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -16,7 +16,6 @@
  * limitations under the License.
  */
 using System;
-using System.Collections.Generic;
 using System.IO;
 
 namespace Avro.IO
@@ -28,6 +27,10 @@ namespace Avro.IO
     {
         private readonly Stream stream;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BinaryDecoder"/> class.
+        /// </summary>
+        /// <param name="stream">Stream to decode.</param>
         public BinaryDecoder(Stream stream)
         {
             this.stream = stream;
@@ -56,17 +59,16 @@ namespace Avro.IO
         /// <summary>
         /// int and long values are written using variable-length, zig-zag coding.
         /// </summary>
-        /// <param name="?"></param>
-        /// <returns></returns>
+        /// <returns>An integer value.</returns>
         public int ReadInt()
         {
             return (int)ReadLong();
         }
+
         /// <summary>
         /// int and long values are written using variable-length, zig-zag coding.
         /// </summary>
-        /// <param name="?"></param>
-        /// <returns></returns>
+        /// <returns>A long value.</returns>
         public long ReadLong()
         {
             byte b = read();
@@ -109,8 +111,7 @@ namespace Avro.IO
         /// The double is converted into a 64-bit integer using a method equivalent to
         /// Java's doubleToLongBits and then encoded in little-endian format.
         /// </summary>
-        /// <param name="?"></param>
-        /// <returns></returns>
+        /// <returns>A double value.</returns>
         public double ReadDouble()
         {
             long bits = (stream.ReadByte() & 0xffL) |
@@ -133,6 +134,10 @@ namespace Avro.IO
             return read(ReadLong());
         }
 
+        /// <summary>
+        /// Reads a string written by <see cref="BinaryEncoder.WriteString(string)"/>.
+        /// </summary>
+        /// <returns>String read from the stream.</returns>
         public string ReadString()
         {
             int length = ReadInt();
@@ -142,97 +147,169 @@ namespace Avro.IO
             return System.Text.Encoding.UTF8.GetString(buffer);
         }
 
+        /// <summary>
+        /// Reads an enumeration.
+        /// </summary>
+        /// <returns>Ordinal value of the enum.</returns>
         public int ReadEnum()
         {
             return ReadInt();
         }
 
+        /// <summary>
+        /// Reads the size of the first block of an array.
+        /// </summary>
+        /// <returns>Size of the first block of an array.</returns>
         public long ReadArrayStart()
         {
             return doReadItemCount();
         }
 
+        /// <summary>
+        /// Processes the next block of an array and returns the number of items in the block and
+        /// let's the caller read those items.
+        /// </summary>
+        /// <returns>Number of items in the next block of an array.</returns>
         public long ReadArrayNext()
         {
             return doReadItemCount();
         }
 
+        /// <summary>
+        /// Reads the size of the next block of map-entries.
+        /// </summary>
+        /// <returns>Size of the next block of map-entries.</returns>
         public long ReadMapStart()
         {
             return doReadItemCount();
         }
 
+        /// <summary>
+        /// Processes the next block of map entries and returns the count of them.
+        /// </summary>
+        /// <returns>Number of entires in the next block of a map.</returns>
         public long ReadMapNext()
         {
             return doReadItemCount();
         }
 
+        /// <summary>
+        /// Reads the tag index of a union written by <see cref="BinaryEncoder.WriteUnionIndex(int)"/>.
+        /// </summary>
+        /// <returns>Tag index of a union.</returns>
         public int ReadUnionIndex()
         {
             return ReadInt();
         }
 
+        /// <summary>
+        /// Reads fixed sized binary object.
+        /// </summary>
+        /// <param name="buffer">Buffer to read the fixed value into.</param>
         public void ReadFixed(byte[] buffer)
         {
             ReadFixed(buffer, 0, buffer.Length);
         }
 
+        /// <summary>
+        /// Reads fixed sized binary object.
+        /// </summary>
+        /// <param name="buffer">Buffer to read the fixed value into.</param>
+        /// <param name="start">
+        /// Position to start writing the fixed value to in the <paramref name="buffer"/>.
+        /// </param>
+        /// <param name="length">
+        /// Number of bytes of the fixed to read.
+        /// </param>
         public void ReadFixed(byte[] buffer, int start, int length)
         {
             Read(buffer, start, length);
         }
 
+        /// <summary>
+        /// Skips over a null value.
+        /// </summary>
         public void SkipNull()
         {
             ReadNull();
         }
 
+        /// <summary>
+        /// Skips over a boolean value.
+        /// </summary>
         public void SkipBoolean()
         {
             ReadBoolean();
         }
 
-
+        /// <summary>
+        /// Skips over an int value.
+        /// </summary>
         public void SkipInt()
         {
             ReadInt();
         }
 
+        /// <summary>
+        /// Skips over a long value.
+        /// </summary>
         public void SkipLong()
         {
             ReadLong();
         }
 
+        /// <summary>
+        /// Skips over a float value.
+        /// </summary>
         public void SkipFloat()
         {
             Skip(4);
         }
 
+        /// <summary>
+        /// Skips over a double value.
+        /// </summary>
         public void SkipDouble()
         {
             Skip(8);
         }
 
+        /// <summary>
+        /// Skips a byte-string written by <see cref="BinaryEncoder.WriteBytes(byte[])"/>.
+        /// </summary>
         public void SkipBytes()
         {
             Skip(ReadLong());
         }
 
+        /// <summary>
+        /// Skips a string written by <see cref="BinaryEncoder.WriteString(string)"/>.
+        /// </summary>
         public void SkipString()
         {
             SkipBytes();
         }
 
+        /// <summary>
+        /// Skips an enum value.
+        /// </summary>
         public void SkipEnum()
         {
             ReadLong();
         }
 
+        /// <summary>
+        /// Skips a union tag index.
+        /// </summary>
         public void SkipUnionIndex()
         {
             ReadLong();
         }
 
+        /// <summary>
+        /// Skips a fixed value of a specified length.
+        /// </summary>
+        /// <param name="len">Length of the fixed to skip.</param>
         public void SkipFixed(int len)
         {
             Skip(len);
@@ -294,6 +371,5 @@ namespace Avro.IO
         {
             throw new NotImplementedException();
         }
-
     }
 }
diff --git a/lang/csharp/src/apache/main/IO/BinaryEncoder.cs b/lang/csharp/src/apache/main/IO/BinaryEncoder.cs
index 560723f..5a2b409 100644
--- a/lang/csharp/src/apache/main/IO/BinaryEncoder.cs
+++ b/lang/csharp/src/apache/main/IO/BinaryEncoder.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -16,7 +16,6 @@
  * limitations under the License.
  */
 using System;
-using System.Collections.Generic;
 using System.IO;
 
 namespace Avro.IO
@@ -28,10 +27,19 @@ namespace Avro.IO
     {
         private readonly Stream Stream;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BinaryEncoder"/> class without a backing
+        /// stream.
+        /// </summary>
         public BinaryEncoder() : this(null)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BinaryEncoder"/> class that writes to
+        /// the provided stream.
+        /// </summary>
+        /// <param name="stream">Stream to write to.</param>
         public BinaryEncoder(Stream stream)
         {
             this.Stream = stream;
@@ -56,7 +64,7 @@ namespace Avro.IO
         /// <summary>
         /// int and long values are written using variable-length, zig-zag coding.
         /// </summary>
-        /// <param name="datum"></param>
+        /// <param name="value">Value to write</param>
         public void WriteInt(int value)
         {
             WriteLong(value);
@@ -64,7 +72,7 @@ namespace Avro.IO
         /// <summary>
         /// int and long values are written using variable-length, zig-zag coding.
         /// </summary>
-        /// <param name="datum"></param>
+        /// <param name="value">Value to write</param>
         public void WriteLong(long value)
         {
             ulong n = (ulong)((value << 1) ^ (value >> 63));
@@ -113,7 +121,6 @@ namespace Avro.IO
         /// Bytes are encoded as a long followed by that many bytes of data.
         /// </summary>
         /// <param name="value"></param>
-        ///
         public void WriteBytes(byte[] value)
         {
             WriteLong(value.Length);
@@ -130,48 +137,58 @@ namespace Avro.IO
             WriteBytes(System.Text.Encoding.UTF8.GetBytes(value));
         }
 
+        /// <inheritdoc/>
         public void WriteEnum(int value)
         {
             WriteLong(value);
         }
 
+        /// <inheritdoc/>
         public void StartItem()
         {
         }
 
+        /// <inheritdoc/>
         public void SetItemCount(long value)
         {
             if (value > 0) WriteLong(value);
         }
 
+        /// <inheritdoc/>
         public void WriteArrayStart()
         {
         }
 
+        /// <inheritdoc/>
         public void WriteArrayEnd()
         {
             WriteLong(0);
         }
 
+        /// <inheritdoc/>
         public void WriteMapStart()
         {
         }
 
+        /// <inheritdoc/>
         public void WriteMapEnd()
         {
             WriteLong(0);
         }
 
+        /// <inheritdoc/>
         public void WriteUnionIndex(int value)
         {
             WriteLong(value);
         }
 
+        /// <inheritdoc/>
         public void WriteFixed(byte[] data)
         {
             WriteFixed(data, 0, data.Length);
         }
 
+        /// <inheritdoc/>
         public void WriteFixed(byte[] data, int start, int len)
         {
             Stream.Write(data, start, len);
@@ -187,6 +204,9 @@ namespace Avro.IO
             Stream.WriteByte(b);
         }
 
+        /// <summary>
+        /// Flushes the underlying stream.
+        /// </summary>
         public void Flush()
         {
             Stream.Flush();
diff --git a/lang/csharp/src/apache/main/IO/ByteBufferInputStream.cs b/lang/csharp/src/apache/main/IO/ByteBufferInputStream.cs
index 6c21161..6725cf7 100644
--- a/lang/csharp/src/apache/main/IO/ByteBufferInputStream.cs
+++ b/lang/csharp/src/apache/main/IO/ByteBufferInputStream.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -21,16 +21,25 @@ using System.IO;
 
 namespace Avro.IO
 {
+    /// <summary>
+    /// Utility to present <see cref="MemoryStream"/>s as an <see cref="InputStream"/>.
+    /// </summary>
+    /// <seealso cref="ByteBufferOutputStream"/>
     public class ByteBufferInputStream : InputStream
     {
         private readonly IList<MemoryStream> _buffers;
         private int _currentBuffer;
 
+        /// <summary>
+        /// Initializes a new instance of a <see cref="ByteBufferInputStream"/>.
+        /// </summary>
+        /// <param name="buffers"></param>
         public ByteBufferInputStream(IList<MemoryStream> buffers)
         {
             _buffers = buffers;
         }
 
+        /// <inheritdoc/>
         public override int Read(byte[] b, int off, int len)
         {
             if (len == 0) return 0;
@@ -68,9 +77,15 @@ namespace Avro.IO
             throw new EndOfStreamException();
         }
 
+        /// <summary>
+        /// Throws a <see cref="NotSupportedException"/>.
+        /// </summary>
+        /// <exception cref="NotSupportedException">
+        /// Always thows.
+        /// </exception>
         public override long Length
         {
             get { throw new NotSupportedException(); }
         }
     }
-}
\ No newline at end of file
+}
diff --git a/lang/csharp/src/apache/main/IO/ByteBufferOutputStream.cs b/lang/csharp/src/apache/main/IO/ByteBufferOutputStream.cs
index bfb6de6..3a55f97 100644
--- a/lang/csharp/src/apache/main/IO/ByteBufferOutputStream.cs
+++ b/lang/csharp/src/apache/main/IO/ByteBufferOutputStream.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -17,14 +17,24 @@
  */
 using System.Collections.Generic;
 using System.IO;
-//using System.Linq;
 
 namespace Avro.IO
 {
+    /// <summary>
+    /// Utility to collect data written to an <see cref="OutputStream"/> in
+    /// <see cref="MemoryStream"/>s.
+    /// </summary>
+    /// <seealso cref="ByteBufferInputStream"/>
     public class ByteBufferOutputStream : OutputStream
     {
+        /// <summary>
+        /// Size of memory stream buffers.
+        /// </summary>
         public const int BUFFER_SIZE = 8192;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ByteBufferOutputStream"/> class.
+        /// </summary>
         public ByteBufferOutputStream()
         {
             Reset();
@@ -42,6 +52,10 @@ namespace Avro.IO
             return new MemoryStream(new byte[BUFFER_SIZE], 0, BUFFER_SIZE, true, true);
         }
 
+        /// <summary>
+        /// Prepends a list of <see cref="MemoryStream"/> to this stream.
+        /// </summary>
+        /// <param name="lists">Memory streams to prepend.</param>
         public void Prepend(List<MemoryStream> lists)
         {
             foreach (var stream in lists)
@@ -52,6 +66,10 @@ namespace Avro.IO
             _buffers.InsertRange(0, lists);
         }
 
+        /// <summary>
+        /// Appends a list of <see cref="MemoryStream"/> to this stream.
+        /// </summary>
+        /// <param name="lists">Memory streams to append.</param>
         public void Append(List<MemoryStream> lists)
         {
             foreach (var stream in lists)
@@ -62,6 +80,7 @@ namespace Avro.IO
             _buffers.AddRange(lists);
         }
 
+        /// <inheritdoc/>
         public override void Write(byte[] b, int off, int len)
         {
             var buffer = _buffers[_buffers.Count -1];
@@ -81,6 +100,10 @@ namespace Avro.IO
             buffer.Write(b, off, len);
         }
 
+        /// <summary>
+        /// Returns all data written and resets the stream to be empty.
+        /// </summary>
+        /// <returns>All memory stream data.</returns>
         public List<MemoryStream> GetBufferList()
         {
             List<MemoryStream> result = _buffers;
@@ -97,6 +120,7 @@ namespace Avro.IO
             return result;
         }
 
+        /// <inheritdoc/>
         public override long Length
         {
             get
@@ -111,8 +135,9 @@ namespace Avro.IO
             }
         }
 
+        /// <inheritdoc/>
         public override void Flush()
         {
         }
     }
-}
\ No newline at end of file
+}
diff --git a/lang/csharp/src/apache/main/IO/Decoder.cs b/lang/csharp/src/apache/main/IO/Decoder.cs
index d0c42e1..573a8dd 100644
--- a/lang/csharp/src/apache/main/IO/Decoder.cs
+++ b/lang/csharp/src/apache/main/IO/Decoder.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,8 +15,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.IO;
 
 namespace Avro.IO
 {
@@ -178,10 +176,20 @@ namespace Avro.IO
         /// </summary>
         void SkipString();
 
+        /// <summary>
+        /// Skips an enumeration.
+        /// </summary>
         void SkipEnum();
 
+        /// <summary>
+        /// Skips a union tag index.
+        /// </summary>
         void SkipUnionIndex();
 
+        /// <summary>
+        /// Skips a fixed of a specified length.
+        /// </summary>
+        /// <param name="len">Length of the fixed.</param>
         void SkipFixed(int len);
     }
 
diff --git a/lang/csharp/src/apache/main/IO/Encoder.cs b/lang/csharp/src/apache/main/IO/Encoder.cs
index 7cee836..e04f3eb 100644
--- a/lang/csharp/src/apache/main/IO/Encoder.cs
+++ b/lang/csharp/src/apache/main/IO/Encoder.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,36 +15,168 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.IO;
 
 namespace Avro.IO
 {
+    /// <summary>
+    /// Defines the interface for a class that provies low-level support for serializing Avro
+    /// values.
+    /// </summary>
     public interface Encoder
     {
+        /// <summary>
+        /// Writes a null value.
+        /// </summary>
         void WriteNull();
+
+        /// <summary>
+        /// Writes a boolean value.
+        /// </summary>
+        /// <param name="value">Value to write.</param>
         void WriteBoolean(bool value);
+
+        /// <summary>
+        /// Writes an int value.
+        /// </summary>
+        /// <param name="value">Value to write.</param>
         void WriteInt(int value);
+
+        /// <summary>
+        /// Writes a long value.
+        /// </summary>
+        /// <param name="value">Value to write.</param>
         void WriteLong(long value);
+
+        /// <summary>
+        /// Writes a float value.
+        /// </summary>
+        /// <param name="value">Value to write.</param>
         void WriteFloat(float value);
+
+        /// <summary>
+        /// Writes a double value.
+        /// </summary>
+        /// <param name="value">Value to write.</param>
         void WriteDouble(double value);
+
+        /// <summary>
+        /// Writes a byte string.
+        /// </summary>
+        /// <param name="value">Value to write.</param>
         void WriteBytes(byte[] value);
+
+        /// <summary>
+        /// Writes an Unicode string.
+        /// </summary>
+        /// <param name="value">Value to write.</param>
         void WriteString(string value);
 
+        /// <summary>
+        /// Writes an enumeration.
+        /// </summary>
+        /// <param name="value">Value to write.</param>
         void WriteEnum(int value);
 
+        /// <summary>
+        /// Call this method before writing a batch of items in an array or a map.
+        /// </summary>
+        /// <param name="value">Number of <see cref="StartItem"/> calls to follow.</param>
         void SetItemCount(long value);
+
+        /// <summary>
+        /// Start a new item of an array or map. See <see cref="WriteArrayStart"/> for usage
+        /// information.
+        /// </summary>
         void StartItem();
 
+        /// <summary>
+        /// Call this method to start writing an array. When starting to serialize an array, call
+        /// <see cref="WriteArrayStart"/>. Then, before writing any data for any item call
+        /// <see cref="SetItemCount(long)"/> followed by a sequence of <see cref="StartItem"/> and
+        /// the item itself. The number of <see cref="StartItem"/> should match the number specified
+        /// in <see cref="SetItemCount(long)"/>. When actually writing the data of the item, you can
+        /// call any <see cref="Encoder"/> method (e.g., <see cref="WriteLong(long)"/>). When all
+        /// items of the array have been written, call <see cref="WriteArrayEnd"/>.
+        /// <example>
+        /// As an example, let's say you want to write an array of records, the record consisting
+        /// of an Long field and a Boolean field. Your code would look something like this:
+        /// <code>
+        /// out.WriteArrayStart();
+        /// out.SetItemCount(list.Count);
+        /// foreach (var r in list)
+        /// {
+        ///     out.StartItem();
+        ///     out.WriteLong(r.LongField);
+        ///     out.WriteBoolean(r.BoolField);
+        /// }
+        /// out.WriteArrayEnd();
+        /// </code>
+        /// </example>
+        /// </summary>
         void WriteArrayStart();
+
+        /// <summary>
+        /// Call this method to finish writing an array. See <see cref="WriteArrayStart"/> for usage
+        /// information.
+        /// </summary>
         void WriteArrayEnd();
 
+        /// <summary>
+        /// Call this to start a new map. See <see cref="WriteArrayStart"/> for details on usage.
+        /// <example>
+        /// As an example of usage, let's say you want to write a map of records, the record
+        /// consisting of an Long field and a Boolean field. Your code would look something like
+        /// this:
+        /// <code>
+        /// out.WriteMapStart();
+        /// out.SetItemCount(dictionary.Count);
+        /// foreach (var entry in dictionary)
+        /// {
+        ///     out.StartItem();
+        ///     out.WriteString(entry.Key);
+        ///     out.writeLong(entry.Value.LongField);
+        ///     out.writeBoolean(entry.Value.BoolField);
+        /// }
+        /// out.WriteMapEnd();
+        /// </code>
+        /// </example>
+        /// </summary>
         void WriteMapStart();
+
+        /// <summary>
+        /// Call this method to terminate the inner-most, currently-opened map. See
+        /// <see cref="WriteArrayStart"/> for more details.
+        /// </summary>
         void WriteMapEnd();
 
+        /// <summary>
+        /// Call this method to write the tag of a union.
+        /// <example>
+        /// As an example of usage, let's say you want to write a union, whose second branch is a
+        /// record consisting of an Long field and a Boolean field. Your code would look something
+        /// like this:
+        /// <code>
+        /// out.WriteIndex(1);
+        /// out.WriteLong(record.LongField);
+        /// out.WriteBoolean(record.BoolField);
+        /// </code>
+        /// </example>
+        /// </summary>
+        /// <param name="value"></param>
         void WriteUnionIndex(int value);
+
+        /// <summary>
+        /// Writes a fixed value.
+        /// </summary>
+        /// <param name="data">The contents to write.</param>
         void WriteFixed(byte[] data);
+
+        /// <summary>
+        /// Writes a fixed value.
+        /// </summary>
+        /// <param name="data">Contents to write.</param>
+        /// <param name="start">Position within data where the contents start.</param>
+        /// <param name="len">Number of bytes to write.</param>
         void WriteFixed(byte[] data, int start, int len);
     }
 }
diff --git a/lang/csharp/src/apache/main/IO/ICallback.cs b/lang/csharp/src/apache/main/IO/ICallback.cs
index 20d5951..9a48f29 100644
--- a/lang/csharp/src/apache/main/IO/ICallback.cs
+++ b/lang/csharp/src/apache/main/IO/ICallback.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -20,18 +20,23 @@ using System;
 
 namespace Avro.IO
 {
+    /// <summary>
+    /// Obsolete - This will be removed from the public API in a future version.
+    /// </summary>
+    /// <typeparam name="T"></typeparam>
+    [Obsolete("This will be removed from the public API in a future version.")]
     public interface ICallback<in T>
     {
-        /**
-         * Receives a callback result.
-         * @param result the result returned in the callback.
-         */
+        /// <summary>
+        /// Receives a callback result.
+        /// </summary>
+        /// <param name="result">Result returned in the callback.</param>
         void HandleResult(T result);
 
-        /**
-         * Receives an error.
-         * @param error the error returned in the callback.
-         */
+        /// <summary>
+        /// Receives an error.
+        /// </summary>
+        /// <param name="exception">Error returned in the callback.</param>
         void HandleException(Exception exception);
     }
-}
\ No newline at end of file
+}
diff --git a/lang/csharp/src/apache/main/IO/InputStream.cs b/lang/csharp/src/apache/main/IO/InputStream.cs
index 8c19fe6..2a92825 100644
--- a/lang/csharp/src/apache/main/IO/InputStream.cs
+++ b/lang/csharp/src/apache/main/IO/InputStream.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -21,42 +21,54 @@ using System.IO;
 
 namespace Avro.IO
 {
+    /// <summary>
+    /// Base class for an input stream.
+    /// </summary>
+    /// <seealso cref="OutputStream"/>
     public abstract class InputStream : Stream
     {
+        /// <inheritdoc/>
         public override void Flush()
         {
         }
 
+        /// <inheritdoc/>
         public override long Seek(long offset, SeekOrigin origin)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override void SetLength(long value)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override void Write(byte[] buffer, int offset, int count)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override bool CanRead
         {
             get { return true; }
         }
 
+        /// <inheritdoc/>
         public override bool CanSeek
         {
             get { return false; }
         }
 
+        /// <inheritdoc/>
         public override bool CanWrite
         {
             get { return false; }
         }
 
+        /// <inheritdoc/>
         public override long Position
         {
             get { throw new NotSupportedException(); }
diff --git a/lang/csharp/src/apache/main/IO/OutputStream.cs b/lang/csharp/src/apache/main/IO/OutputStream.cs
index 2556dbe..b80f445 100644
--- a/lang/csharp/src/apache/main/IO/OutputStream.cs
+++ b/lang/csharp/src/apache/main/IO/OutputStream.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -21,39 +21,50 @@ using System.IO;
 
 namespace Avro.IO
 {
+    /// <summary>
+    /// Base class for an output stream.
+    /// </summary>
+    /// <seealso cref="InputStream"/>
     public abstract class OutputStream : Stream
     {
+        /// <inheritdoc/>
         public override bool CanWrite
         {
             get { return true; }
         }
 
+        /// <inheritdoc/>
         public override bool CanRead
         {
             get { return false; }
         }
 
+        /// <inheritdoc/>
         public override bool CanSeek
         {
             get { return false; }
         }
 
+        /// <inheritdoc/>
         public override long Position
         {
             get { throw new NotSupportedException(); }
             set { throw new NotSupportedException(); }
         }
 
+        /// <inheritdoc/>
         public override int Read(byte[] buffer, int offset, int count)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override long Seek(long offset, SeekOrigin origin)
         {
             throw new NotSupportedException();
         }
 
+        /// <inheritdoc/>
         public override void SetLength(long value)
         {
             throw new NotSupportedException();
diff --git a/lang/csharp/src/apache/main/IO/Resolver.cs b/lang/csharp/src/apache/main/IO/Resolver.cs
index d48fdde..c77aca7 100644
--- a/lang/csharp/src/apache/main/IO/Resolver.cs
+++ b/lang/csharp/src/apache/main/IO/Resolver.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
diff --git a/lang/csharp/src/apache/main/Protocol/Message.cs b/lang/csharp/src/apache/main/Protocol/Message.cs
index 506610b..49b53f8 100644
--- a/lang/csharp/src/apache/main/Protocol/Message.cs
+++ b/lang/csharp/src/apache/main/Protocol/Message.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -16,13 +16,13 @@
  * limitations under the License.
  */
 using System;
-using System.Collections.Generic;
-using System.Text;
 using Newtonsoft.Json.Linq;
-using Newtonsoft.Json;
 
 namespace Avro
 {
+    /// <summary>
+    /// Represents a message in an Avro protocol.
+    /// </summary>
     public class Message
     {
         /// <summary>
@@ -68,6 +68,11 @@ namespace Avro
         /// <param name="request">list of parameters</param>
         /// <param name="response">response property</param>
         /// <param name="error">error union schema</param>
+        /// <param name="oneway">
+        /// Indicates that this is a one-way message. This may only be true when
+        /// <paramref name="response"/> is <see cref="Schema.Type.Null"/> and there are no errors
+        /// listed.
+        /// </param>
         public Message(string name, string doc, RecordSchema request, Schema response, UnionSchema error, bool? oneway)
         {
             if (string.IsNullOrEmpty(name)) throw new ArgumentNullException("name", "name cannot be null.");
diff --git a/lang/csharp/src/apache/main/Protocol/Protocol.cs b/lang/csharp/src/apache/main/Protocol/Protocol.cs
index 4fde7a6..8845c1a 100644
--- a/lang/csharp/src/apache/main/Protocol/Protocol.cs
+++ b/lang/csharp/src/apache/main/Protocol/Protocol.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -17,13 +17,14 @@
  */
 using System;
 using System.Collections.Generic;
-using System.Linq;
 using System.Text;
-using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
 
 namespace Avro
 {
+    /// <summary>
+    /// A set of messages forming an application protocol.
+    /// </summary>
     public class Protocol
     {
         /// <summary>
@@ -52,6 +53,10 @@ namespace Avro
         public IDictionary<string,Message> Messages { get; set; }
 
         private byte[] md5;
+
+        /// <summary>
+        /// MD5 hash of the text of this protocol.
+        /// </summary>
         public byte[] MD5
         {
             get
diff --git a/lang/csharp/src/apache/main/Protocol/ProtocolParseException.cs b/lang/csharp/src/apache/main/Protocol/ProtocolParseException.cs
index beb6959..94fcdf1 100644
--- a/lang/csharp/src/apache/main/Protocol/ProtocolParseException.cs
+++ b/lang/csharp/src/apache/main/Protocol/ProtocolParseException.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -16,18 +16,31 @@
  * limitations under the License.
  */
 using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Avro
 {
-    public class ProtocolParseException:AvroException
+    /// <summary>
+    /// Used to communicate an exception that occurred while parsing a protocol.
+    /// </summary>
+    public class ProtocolParseException : AvroException
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ProtocolParseException"/> class.
+        /// </summary>
+        /// <param name="s">Exception message.</param>
         public ProtocolParseException(string s)
             : base(s)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ProtocolParseException"/> class.
+        /// </summary>
+        /// <param name="s">Exception message.</param>
+        /// <param name="inner">
+        /// The exception that is the cause of the current exception, or a null reference
+        /// if no inner exception is specified.
+        /// </param>
         public ProtocolParseException(string s, Exception inner)
             : base(s, inner)
         {
diff --git a/lang/csharp/src/apache/main/Schema/ArraySchema.cs b/lang/csharp/src/apache/main/Schema/ArraySchema.cs
index ef02fe5..ea8dc7a 100644
--- a/lang/csharp/src/apache/main/Schema/ArraySchema.cs
+++ b/lang/csharp/src/apache/main/Schema/ArraySchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -35,6 +35,7 @@ namespace Avro
         /// Static class to return a new instance of ArraySchema
         /// </summary>
         /// <param name="jtok">JSON object for the array schema</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         /// <param name="names">list of named schemas already parsed</param>
         /// <param name="encspace">enclosing namespace for the array schema</param>
         /// <returns></returns>
@@ -50,6 +51,7 @@ namespace Avro
         /// Constructor
         /// </summary>
         /// <param name="items">schema for the array items type</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         private ArraySchema(Schema items, PropertyMap props) : base(Type.Array, props)
         {
             if (null == items) throw new ArgumentNullException("items");
diff --git a/lang/csharp/src/apache/main/Schema/AvroException.cs b/lang/csharp/src/apache/main/Schema/AvroException.cs
index 51a8f9b..7d0eb2c 100644
--- a/lang/csharp/src/apache/main/Schema/AvroException.cs
+++ b/lang/csharp/src/apache/main/Schema/AvroException.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -16,18 +16,31 @@
  * limitations under the License.
  */
 using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Avro
 {
+    /// <summary>
+    /// A generic Avro exception.
+    /// </summary>
     public class AvroException : Exception
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AvroException"/> class.
+        /// </summary>
+        /// <param name="s">The message that describes the error.</param>
         public AvroException(string s)
             : base(s)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AvroException"/> class.
+        /// </summary>
+        /// <param name="s">The message that describes the error.</param>
+        /// <param name="inner">
+        /// The exception that is the cause of the current exception, or a null reference
+        /// if no inner exception is specified.
+        /// </param>
         public AvroException(string s, Exception inner)
             : base(s, inner)
         {
diff --git a/lang/csharp/src/apache/main/Schema/AvroTypeException.cs b/lang/csharp/src/apache/main/Schema/AvroTypeException.cs
index 6ca347b..141513f 100644
--- a/lang/csharp/src/apache/main/Schema/AvroTypeException.cs
+++ b/lang/csharp/src/apache/main/Schema/AvroTypeException.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,14 +15,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Avro
 {
+    /// <summary>
+    /// Used to communicate an exception associated with Avro typing.
+    /// </summary>
     public class AvroTypeException : AvroException
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AvroTypeException"/> class.
+        /// </summary>
+        /// <param name="s"></param>
         public AvroTypeException(string s)
             : base(s)
         {
diff --git a/lang/csharp/src/apache/main/Schema/EnumSchema.cs b/lang/csharp/src/apache/main/Schema/EnumSchema.cs
index fa0bd30..5a4f5c8 100644
--- a/lang/csharp/src/apache/main/Schema/EnumSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/EnumSchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -46,6 +46,7 @@ namespace Avro
         /// Static function to return new instance of EnumSchema
         /// </summary>
         /// <param name="jtok">JSON object for enum schema</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         /// <param name="names">list of named schema already parsed in</param>
         /// <param name="encspace">enclosing namespace for the enum schema</param>
         /// <returns>new instance of enum schema</returns>
diff --git a/lang/csharp/src/apache/main/Schema/Field.cs b/lang/csharp/src/apache/main/Schema/Field.cs
index daa96f7..e83ee7c 100644
--- a/lang/csharp/src/apache/main/Schema/Field.cs
+++ b/lang/csharp/src/apache/main/Schema/Field.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -17,7 +17,6 @@
  */
 using System;
 using System.Collections.Generic;
-using System.Text;
 using Newtonsoft.Json.Linq;
 using Newtonsoft.Json;
 
@@ -34,8 +33,19 @@ namespace Avro
         /// </summary>
         public enum SortOrder
         {
+            /// <summary>
+            /// Ascending order.
+            /// </summary>
             ascending,
+
+            /// <summary>
+            /// Descending order.
+            /// </summary>
             descending,
+
+            /// <summary>
+            /// Ignore sort order.
+            /// </summary>
             ignore
         }
 
@@ -102,6 +112,7 @@ namespace Avro
         /// <param name="doc">documentation for the field</param>
         /// <param name="defaultValue">field's default value if it exists</param>
         /// <param name="sortorder">sort order of the field</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         internal Field(Schema schema, string name, IList<string> aliases, int pos, string doc,
                         JToken defaultValue, SortOrder sortorder, PropertyMap props)
         {
diff --git a/lang/csharp/src/apache/main/Schema/FixedSchema.cs b/lang/csharp/src/apache/main/Schema/FixedSchema.cs
index 93d65ec..cc10e3b 100644
--- a/lang/csharp/src/apache/main/Schema/FixedSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/FixedSchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -36,6 +36,7 @@ namespace Avro
         /// Static function to return new instance of the fixed schema class
         /// </summary>
         /// <param name="jtok">JSON object for the fixed schema</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         /// <param name="names">list of named schema already parsed in</param>
         /// <param name="encspace">enclosing namespace of the fixed schema</param>
         /// <returns></returns>
diff --git a/lang/csharp/src/apache/main/Schema/JsonHelper.cs b/lang/csharp/src/apache/main/Schema/JsonHelper.cs
index ad664ce..a606f54 100644
--- a/lang/csharp/src/apache/main/Schema/JsonHelper.cs
+++ b/lang/csharp/src/apache/main/Schema/JsonHelper.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
diff --git a/lang/csharp/src/apache/main/Schema/MapSchema.cs b/lang/csharp/src/apache/main/Schema/MapSchema.cs
index 0570c9f..4da82c2 100644
--- a/lang/csharp/src/apache/main/Schema/MapSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/MapSchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -32,6 +32,11 @@ namespace Avro
         /// </summary>
         public Schema ValueSchema { get; set; }
 
+        /// <summary>
+        /// Creates a new <see cref="MapSchema"/> from the given schema.
+        /// </summary>
+        /// <param name="type">Schema to create the map schema from.</param>
+        /// <returns>A new <see cref="MapSchema"/>.</returns>
         public static MapSchema CreateMap(Schema type)
         {
             return new MapSchema(type,null);
@@ -41,6 +46,7 @@ namespace Avro
         /// Static function to return new instance of map schema
         /// </summary>
         /// <param name="jtok">JSON object for the map schema</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         /// <param name="names">list of named schemas already read</param>
         /// <param name="encspace">enclosing namespace of the map schema</param>
         /// <returns></returns>
@@ -56,6 +62,7 @@ namespace Avro
         /// Constructor for map schema class
         /// </summary>
         /// <param name="valueSchema">schema for map values type</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         private MapSchema(Schema valueSchema, PropertyMap props) : base(Type.Map, props)
         {
             if (null == valueSchema) throw new ArgumentNullException("valueSchema", "valueSchema cannot be null.");
diff --git a/lang/csharp/src/apache/main/Schema/NamedSchema.cs b/lang/csharp/src/apache/main/Schema/NamedSchema.cs
index f47f299..2c73210 100644
--- a/lang/csharp/src/apache/main/Schema/NamedSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/NamedSchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -71,6 +71,7 @@ namespace Avro
         /// Static function to return a new instance of the named schema
         /// </summary>
         /// <param name="jo">JSON object of the named schema</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         /// <param name="names">list of named schemas already read</param>
         /// <param name="encspace">enclosing namespace of the named schema</param>
         /// <returns></returns>
@@ -157,6 +158,14 @@ namespace Avro
             return aliases;
         }
 
+        /// <summary>
+        /// Determines whether the given schema name is one of this <see cref="NamedSchema"/>'s
+        /// aliases.
+        /// </summary>
+        /// <param name="name">Schema name to test.</param>
+        /// <returns>
+        /// True if <paramref name="name"/> is one of this schema's aliases; false otherwise.
+        /// </returns>
         protected bool InAliases(SchemaName name)
         {
             if (null != aliases)
diff --git a/lang/csharp/src/apache/main/Schema/PrimitiveSchema.cs b/lang/csharp/src/apache/main/Schema/PrimitiveSchema.cs
index 6368cde..703519c 100644
--- a/lang/csharp/src/apache/main/Schema/PrimitiveSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/PrimitiveSchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -31,6 +31,7 @@ namespace Avro
         /// Constructor for primitive schema
         /// </summary>
         /// <param name="type"></param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         private PrimitiveSchema(Type type, PropertyMap props) : base(type, props)
         {
         }
@@ -39,6 +40,7 @@ namespace Avro
         /// Static function to return new instance of primitive schema
         /// </summary>
         /// <param name="type">primitive type</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         /// <returns></returns>
         public static PrimitiveSchema NewInstance(string type, PropertyMap props = null)
         {
diff --git a/lang/csharp/src/apache/main/Schema/Property.cs b/lang/csharp/src/apache/main/Schema/Property.cs
index 862c4f1..50ca739 100644
--- a/lang/csharp/src/apache/main/Schema/Property.cs
+++ b/lang/csharp/src/apache/main/Schema/Property.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,15 +15,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
 using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 using Newtonsoft.Json.Linq;
 using Newtonsoft.Json;
 
 namespace Avro
 {
+    /// <summary>
+    /// Provides access to custom properties (those not defined in the Avro spec) in a JSON object.
+    /// </summary>
     public class PropertyMap : Dictionary<string, string>
     {
         /// <summary>
diff --git a/lang/csharp/src/apache/main/Schema/RecordSchema.cs b/lang/csharp/src/apache/main/Schema/RecordSchema.cs
index a6de56d..b451d3a 100644
--- a/lang/csharp/src/apache/main/Schema/RecordSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/RecordSchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -17,9 +17,7 @@
  */
 using System;
 using System.Collections.Generic;
-using System.Text;
 using Newtonsoft.Json.Linq;
-using Newtonsoft.Json;
 
 namespace Avro
 {
@@ -53,6 +51,7 @@ namespace Avro
         /// </summary>
         /// <param name="type">type of record schema, either record or error</param>
         /// <param name="jtok">JSON object for the record schema</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         /// <param name="names">list of named schema already read</param>
         /// <param name="encspace">enclosing namespace of the records schema</param>
         /// <returns>new RecordSchema object</returns>
@@ -181,10 +180,29 @@ namespace Avro
             return fieldLookup.ContainsKey(fieldName);
         }
 
+        /// <summary>
+        /// Gets a field with a specified name.
+        /// </summary>
+        /// <param name="fieldName">Name of the field to get.</param>
+        /// <param name="field">
+        /// When this method returns true, contains the field with the specified name. When this
+        /// method returns false, null.
+        /// </param>
+        /// <returns>True if a field with the specified name exists; false otherwise.</returns>
         public bool TryGetField(string fieldName, out Field field)
         {
             return fieldLookup.TryGetValue(fieldName, out field);
         }
+
+        /// <summary>
+        /// Gets a field with a specified alias.
+        /// </summary>
+        /// <param name="fieldName">Alias of the field to get.</param>
+        /// <param name="field">
+        /// When this method returns true, contains the field with the specified alias. When this
+        /// method returns false, null.
+        /// </param>
+        /// <returns>True if a field with the specified alias exists; false otherwise.</returns>
         public bool TryGetFieldAlias(string fieldName, out Field field)
         {
             return fieldAliasLookup.TryGetValue(fieldName, out field);
diff --git a/lang/csharp/src/apache/main/Schema/Schema.cs b/lang/csharp/src/apache/main/Schema/Schema.cs
index ba14e2e..9f4fcb8 100644
--- a/lang/csharp/src/apache/main/Schema/Schema.cs
+++ b/lang/csharp/src/apache/main/Schema/Schema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -33,20 +33,79 @@ namespace Avro
         /// </summary>
         public enum Type
         {
+            /// <summary>
+            /// No value.
+            /// </summary>
             Null,
+
+            /// <summary>
+            /// A binary value.
+            /// </summary>
             Boolean,
+
+            /// <summary>
+            /// A 32-bit signed integer.
+            /// </summary>
             Int,
+
+            /// <summary>
+            /// A 64-bit signed integer.
+            /// </summary>
             Long,
+
+            /// <summary>
+            /// A single precision (32-bit) IEEE 754 floating-point number.
+            /// </summary>
             Float,
+
+            /// <summary>
+            /// A double precision (64-bit) IEEE 754 floating-point number.
+            /// </summary>
             Double,
+
+            /// <summary>
+            /// A sequence of 8-bit unsigned bytes.
+            /// </summary>
             Bytes,
+
+            /// <summary>
+            /// An unicode character sequence.
+            /// </summary>
             String,
+
+            /// <summary>
+            /// A logical collection of fields.
+            /// </summary>
             Record,
+
+            /// <summary>
+            /// An enumeration.
+            /// </summary>
             Enumeration,
+
+            /// <summary>
+            /// An array of values.
+            /// </summary>
             Array,
+
+            /// <summary>
+            /// A map of values with string keys.
+            /// </summary>
             Map,
+
+            /// <summary>
+            /// A union.
+            /// </summary>
             Union,
+
+            /// <summary>
+            /// A fixed-length byte string.
+            /// </summary>
             Fixed,
+
+            /// <summary>
+            /// A protocol error.
+            /// </summary>
             Error
         }
 
@@ -64,6 +123,7 @@ namespace Avro
         /// Constructor for schema class
         /// </summary>
         /// <param name="type"></param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         protected Schema(Type type, PropertyMap props)
         {
             this.Tag = type;
diff --git a/lang/csharp/src/apache/main/Schema/SchemaName.cs b/lang/csharp/src/apache/main/Schema/SchemaName.cs
index 241b832..ae6f0b8 100644
--- a/lang/csharp/src/apache/main/Schema/SchemaName.cs
+++ b/lang/csharp/src/apache/main/Schema/SchemaName.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -17,7 +17,6 @@
  */
 using System;
 using System.Collections.Generic;
-using System.Text;
 
 namespace Avro
 {
@@ -133,6 +132,7 @@ namespace Avro
             return obj1 == null ? obj2 == null : obj1.Equals(obj2);
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             return string.IsNullOrEmpty(Fullname) ? 0 : 29 * Fullname.GetHashCode();
diff --git a/lang/csharp/src/apache/main/Schema/SchemaNormalization.cs b/lang/csharp/src/apache/main/Schema/SchemaNormalization.cs
index 47199b7..c7ea9d6 100644
--- a/lang/csharp/src/apache/main/Schema/SchemaNormalization.cs
+++ b/lang/csharp/src/apache/main/Schema/SchemaNormalization.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -27,6 +27,16 @@ namespace Avro
     /// </summary>
     public static class SchemaNormalization
     {
+        /// <summary>
+        /// Obsolete: This will be removed from the public API in a future version.
+        /// This should be a private const field, similar to the Java implementation. It appears
+        /// that this was originally exposed for unit tests. Unit tests should hard-code this value
+        /// rather than access it here.
+        ///
+        /// NOTE: When this is made private, remove the obsolete warning suppression around usages
+        /// of this field in this class.
+        /// </summary>
+        [Obsolete("This will be removed from the public API in a future version.")]
         public static long Empty64 = -4513414715797952619;
 
         /// <summary>
@@ -121,7 +131,10 @@ namespace Avro
         /// <returns>Fingerprint</returns>
         private static long Fingerprint64(byte[] data)
         {
+#pragma warning disable CS0618 // Type or member is obsolete - remove with Empty64 made private.
             long result = Empty64;
+#pragma warning restore CS0618 // Type or member is obsolete
+
             foreach (var b in data)
             {
                 result = ((long)(((ulong)result) >> 8)) ^ Fp64.FpTable[(int) (result ^ b) & 0xff];
@@ -246,7 +259,10 @@ namespace Avro
                     for (int j = 0; j < 8; j++)
                     {
                         long mask = -(fp & 1L);
+
+#pragma warning disable CS0618 // Type or member is obsolete - remove with Empty64 made private.
                         fp = ((long) (((ulong) fp) >> 1)) ^ (Empty64 & mask);
+#pragma warning restore CS0618 // Type or member is obsolete
                     }
                     FpTable[i] = fp;
                 }
diff --git a/lang/csharp/src/apache/main/Schema/SchemaParseException.cs b/lang/csharp/src/apache/main/Schema/SchemaParseException.cs
index 97af24f..987b2e2 100644
--- a/lang/csharp/src/apache/main/Schema/SchemaParseException.cs
+++ b/lang/csharp/src/apache/main/Schema/SchemaParseException.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,14 +15,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Avro
 {
-    public class SchemaParseException:AvroException
+    /// <summary>
+    /// Used to communicate an exception that occurred while parsing a schema.
+    /// </summary>
+    public class SchemaParseException : AvroException
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SchemaParseException"/> class.
+        /// </summary>
+        /// <param name="s">Exception message.</param>
         public SchemaParseException(string s)
             : base(s)
         {
diff --git a/lang/csharp/src/apache/main/Schema/UnionSchema.cs b/lang/csharp/src/apache/main/Schema/UnionSchema.cs
index 13f9109..3bdc8ea 100644
--- a/lang/csharp/src/apache/main/Schema/UnionSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/UnionSchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -42,6 +42,7 @@ namespace Avro
         /// Static function to return instance of the union schema
         /// </summary>
         /// <param name="jarr">JSON object for the union schema</param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         /// <param name="names">list of named schemas already read</param>
         /// <param name="encspace">enclosing namespace of the schema</param>
         /// <returns>new UnionSchema object</returns>
@@ -71,6 +72,7 @@ namespace Avro
         /// Contructor for union schema
         /// </summary>
         /// <param name="schemas"></param>
+        /// <param name="props">dictionary that provides access to custom properties</param>
         private UnionSchema(List<Schema> schemas, PropertyMap props) : base(Type.Union, props)
         {
             if (schemas == null)
diff --git a/lang/csharp/src/apache/main/Schema/UnnamedSchema.cs b/lang/csharp/src/apache/main/Schema/UnnamedSchema.cs
index 3c105f7..96f2b0d 100644
--- a/lang/csharp/src/apache/main/Schema/UnnamedSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/UnnamedSchema.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,10 +15,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 
 namespace Avro
 {
@@ -27,10 +23,16 @@ namespace Avro
     /// </summary>
     public abstract class UnnamedSchema : Schema
     {
+        /// <summary>
+        /// Base constructor for an <see cref="UnnamedSchema"/>.
+        /// </summary>
+        /// <param name="type">Type of schema.</param>
+        /// <param name="props">Dictionary that provides access to custom properties</param>
         protected UnnamedSchema(Type type, PropertyMap props) : base(type, props)
         {
         }
 
+        /// <inheritdoc/>
         public override string Name
         {
             get { return Tag.ToString().ToLower(); }
diff --git a/lang/csharp/src/apache/main/Specific/ObjectCreator.cs b/lang/csharp/src/apache/main/Specific/ObjectCreator.cs
index 61e1261..d794963 100644
--- a/lang/csharp/src/apache/main/Specific/ObjectCreator.cs
+++ b/lang/csharp/src/apache/main/Specific/ObjectCreator.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -53,6 +53,10 @@ namespace Avro.Specific
         private readonly Assembly entryAssembly;
         private readonly bool diffAssembly;
 
+        /// <summary>
+        /// Obsolete: This will be removed from the public API in a future version.
+        /// </summary>
+        /// <returns>Obsolete</returns>
         [Obsolete("This will be removed from the public API in a future version.")]
         public delegate object CtorDelegate();
 
@@ -69,6 +73,10 @@ namespace Avro.Specific
             diffAssembly = entryAssembly != null && execAssembly != entryAssembly;
         }
 
+#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
+        /// <summary>
+        /// Obsolete: This will be removed from the public API in a future version.
+        /// </summary>
         [Obsolete("This will be removed from the public API in a future version.")]
         public struct NameCtorKey : IEquatable<NameCtorKey>
         {
@@ -108,6 +116,7 @@ namespace Avro.Specific
                 return !left.Equals(right);
             }
         }
+#pragma warning restore CS1591 // Missing XML comment for publicly visible type or member
 
         /// <summary>
         /// Find the type with the given name
diff --git a/lang/csharp/src/apache/main/Specific/SpecificDatumReader.cs b/lang/csharp/src/apache/main/Specific/SpecificDatumReader.cs
index 42805de..2b98229 100644
--- a/lang/csharp/src/apache/main/Specific/SpecificDatumReader.cs
+++ b/lang/csharp/src/apache/main/Specific/SpecificDatumReader.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -21,14 +21,22 @@ using Avro.IO;
 
 namespace Avro.Specific
 {
+    /// <summary>
     /// PreresolvingDatumReader for reading data to ISpecificRecord classes.
+    /// </summary>
     /// <see cref="PreresolvingDatumReader{T}">For more information about performance considerations for choosing this implementation</see>
     public class SpecificDatumReader<T> : PreresolvingDatumReader<T>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SpecificDatumReader{T}"/> class.
+        /// </summary>
+        /// <param name="writerSchema">Schema that was used to write the data.</param>
+        /// <param name="readerSchema">Schema to use when reading the data.</param>
         public SpecificDatumReader(Schema writerSchema, Schema readerSchema) : base(writerSchema, readerSchema)
         {
         }
 
+        /// <inheritdoc/>
         protected override bool IsReusable(Schema.Type tag)
         {
             switch (tag)
@@ -47,21 +55,25 @@ namespace Avro.Specific
             return true;
         }
 
+        /// <inheritdoc/>
         protected override ArrayAccess GetArrayAccess(ArraySchema readerSchema)
         {
             return new SpecificArrayAccess(readerSchema);
         }
 
+        /// <inheritdoc/>
         protected override EnumAccess GetEnumAccess(EnumSchema readerSchema)
         {
             return new SpecificEnumAccess();
         }
 
+        /// <inheritdoc/>
         protected override MapAccess GetMapAccess(MapSchema readerSchema)
         {
             return new SpecificMapAccess(readerSchema);
         }
 
+        /// <inheritdoc/>
         protected override RecordAccess GetRecordAccess(RecordSchema readerSchema)
         {
             if (readerSchema.Name == null)
@@ -72,6 +84,7 @@ namespace Avro.Specific
             return new SpecificRecordAccess(readerSchema);
         }
 
+        /// <inheritdoc/>
         protected override FixedAccess GetFixedAccess(FixedSchema readerSchema)
         {
             return new SpecificFixedAccess(readerSchema);
diff --git a/lang/csharp/src/apache/main/Specific/SpecificDatumWriter.cs b/lang/csharp/src/apache/main/Specific/SpecificDatumWriter.cs
index 15bce81..f41849a 100644
--- a/lang/csharp/src/apache/main/Specific/SpecificDatumWriter.cs
+++ b/lang/csharp/src/apache/main/Specific/SpecificDatumWriter.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -24,14 +24,19 @@ namespace Avro.Specific
 {
     /// <summary>
     /// PreresolvingDatumWriter for writing data from ISpecificRecord classes.
-    /// <see cref="PreresolvingDatumWriter{T}">For more information about performance considerations for choosing this implementation</see>
     /// </summary>
+    /// <see cref="PreresolvingDatumWriter{T}">For more information about performance considerations for choosing this implementation</see>
     public class SpecificDatumWriter<T> : PreresolvingDatumWriter<T>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SpecificDatumWriter{T}"/> class.
+        /// </summary>
+        /// <param name="schema">Schema to use when writing data.</param>
         public SpecificDatumWriter(Schema schema) : base(schema, new SpecificArrayAccess(), new DictionaryMapAccess())
         {
         }
 
+        /// <inheritdoc/>
         protected override void WriteRecordFields(object recordObj, RecordFieldWriter[] writers, Encoder encoder)
         {
             var record = (ISpecificRecord) recordObj;
@@ -42,17 +47,20 @@ namespace Avro.Specific
             }
         }
 
+        /// <inheritdoc/>
         protected override void EnsureRecordObject(RecordSchema recordSchema, object value)
         {
             if (!(value is ISpecificRecord))
                 throw new AvroTypeException("Record object is not derived from ISpecificRecord");
         }
 
+        /// <inheritdoc/>
         protected override void WriteField(object record, string fieldName, int fieldPos, WriteItem writer, Encoder encoder)
         {
             writer(((ISpecificRecord)record).Get(fieldPos), encoder);
         }
 
+        /// <inheritdoc/>
         protected override WriteItem ResolveEnum(EnumSchema es)
         {
             var type = ObjectCreator.Instance.GetType(es);
@@ -94,6 +102,7 @@ namespace Avro.Specific
                        };
         }
 
+        /// <inheritdoc/>
         protected override void WriteFixed(FixedSchema schema, object value, Encoder encoder)
         {
             var fixedrec = value as SpecificFixed;
@@ -103,6 +112,7 @@ namespace Avro.Specific
             encoder.WriteFixed(fixedrec.Value);
         }
 
+        /// <inheritdoc/>
         protected override bool UnionBranchMatches( Schema sc, object obj )
         {
             if (obj == null && sc.Tag != Avro.Schema.Type.Null) return false;
@@ -169,4 +179,4 @@ namespace Avro.Specific
             }
         }
     }
-}
\ No newline at end of file
+}
diff --git a/lang/csharp/src/apache/main/Specific/SpecificException.cs b/lang/csharp/src/apache/main/Specific/SpecificException.cs
index a1e0c1a..c892a45 100644
--- a/lang/csharp/src/apache/main/Specific/SpecificException.cs
+++ b/lang/csharp/src/apache/main/Specific/SpecificException.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -20,10 +20,18 @@ using System;
 
 namespace Avro.Specific
 {
+    /// <summary>
+    /// Base class for specific exceptions.
+    /// </summary>
     public abstract class SpecificException : Exception, ISpecificRecord
     {
+        /// <inheritdoc/>
         public abstract Schema Schema { get; }
+
+        /// <inheritdoc/>
         public abstract object Get(int fieldPos);
+
+        /// <inheritdoc/>
         public abstract void Put(int fieldPos, object fieldValue);
     }
-}
\ No newline at end of file
+}
diff --git a/lang/csharp/src/apache/main/Specific/SpecificFixed.cs b/lang/csharp/src/apache/main/Specific/SpecificFixed.cs
index fabcb0d..119f112 100644
--- a/lang/csharp/src/apache/main/Specific/SpecificFixed.cs
+++ b/lang/csharp/src/apache/main/Specific/SpecificFixed.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -28,9 +28,22 @@ namespace Avro.Specific
     /// </summary>
     public abstract class SpecificFixed : GenericFixed
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SpecificFixed"/> class.
+        /// </summary>
+        /// <param name="size"></param>
         public SpecificFixed(uint size) : base(size) { }
+
+        /// <summary>
+        /// Schema of this instance.
+        /// </summary>
         public abstract new Schema Schema { get; }
 
+        /// <summary>
+        /// Determines whether the provided fixed is equivalent this this instance.
+        /// </summary>
+        /// <param name="obj">Fixed to compare.</param>
+        /// <returns>True if the fixed instances have equal values.</returns>
         protected bool Equals(SpecificFixed obj)
         {
             if (this == obj) return true;
@@ -47,6 +60,7 @@ namespace Avro.Specific
 
         }
 
+        /// <inheritdoc/>
         public override bool Equals(object obj)
         {
             if (ReferenceEquals(null, obj)) return false;
@@ -55,6 +69,7 @@ namespace Avro.Specific
             return Equals((SpecificFixed) obj);
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             int result = Schema.GetHashCode();
diff --git a/lang/csharp/src/apache/main/Specific/SpecificProtocol.cs b/lang/csharp/src/apache/main/Specific/SpecificProtocol.cs
index dff0983..65a3c71 100644
--- a/lang/csharp/src/apache/main/Specific/SpecificProtocol.cs
+++ b/lang/csharp/src/apache/main/Specific/SpecificProtocol.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -17,15 +17,40 @@
  */
 namespace Avro.Specific
 {
+    /// <summary>
+    /// Defines the interface for a class that implements a specific protocol.
+    /// TODO: This interface needs better documentation.
+    /// </summary>
     public interface ISpecificProtocol
     {
+        /// <summary>
+        /// Protocol for this instance.
+        /// </summary>
         Protocol Protocol { get; }
+
+        /// <summary>
+        /// Execute a request.
+        /// </summary>
+        /// <param name="requestor">Callback requestor.</param>
+        /// <param name="messageName">Name of the message.</param>
+        /// <param name="args">Arguments for the message.</param>
+        /// <param name="callback">Callback.</param>
         void Request(ICallbackRequestor requestor, string messageName, object[] args, object callback);
     }
 
+    /// <summary>
+    /// TODO: This interface needs better documentation.
+    /// </summary>
     public interface ICallbackRequestor
     {
+        /// <summary>
+        /// Request
+        /// </summary>
+        /// <typeparam name="T">Type</typeparam>
+        /// <param name="messageName">Name of the message.</param>
+        /// <param name="args">Arguments for the message.</param>
+        /// <param name="callback">Callback.</param>
         void Request<T>(string messageName, object[] args, object callback);
     }
 
-}
\ No newline at end of file
+}
diff --git a/lang/csharp/src/apache/main/Specific/SpecificReader.cs b/lang/csharp/src/apache/main/Specific/SpecificReader.cs
index fd9f982..a8e8e59 100644
--- a/lang/csharp/src/apache/main/Specific/SpecificReader.cs
+++ b/lang/csharp/src/apache/main/Specific/SpecificReader.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -58,6 +58,11 @@ namespace Avro.Specific
             reader = new SpecificDefaultReader(writerSchema, readerSchema);
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SpecificReader{T}"/> class using an
+        /// existing <see cref="SpecificDefaultReader"/>.
+        /// </summary>
+        /// <param name="reader">Default reader to use.</param>
         public SpecificReader(SpecificDefaultReader reader)
         {
             this.reader = reader;
@@ -253,8 +258,7 @@ namespace Avro.Specific
         /// Gets the target type name in the given schema
         /// </summary>
         /// <param name="schema">schema containing the type to be determined</param>
-        /// <param name="nullible">used for union schema</param>
-        /// <returns></returns>
+        /// <returns>Name of the type</returns>
         protected virtual string getTargetType(Schema schema)
         {
             bool nEnum = false;
diff --git a/lang/csharp/src/apache/main/Specific/SpecificRecord.cs b/lang/csharp/src/apache/main/Specific/SpecificRecord.cs
index 183e730..417b0b6 100644
--- a/lang/csharp/src/apache/main/Specific/SpecificRecord.cs
+++ b/lang/csharp/src/apache/main/Specific/SpecificRecord.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,10 +15,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 
 namespace Avro.Specific
 {
@@ -27,8 +23,27 @@ namespace Avro.Specific
     /// </summary>
     public interface ISpecificRecord
     {
+        /// <summary>
+        /// Schema of this instance.
+        /// </summary>
         Schema Schema { get; }
+
+        /// <summary>
+        /// Return the value of a field given its position in the schema.
+        /// This method is not meant to be called by user code, but only by
+        /// <see cref="SpecificDatumReader{T}"/> implementations.
+        /// </summary>
+        /// <param name="fieldPos">Position of the field.</param>
+        /// <returns>Value of the field.</returns>
         object Get(int fieldPos);
+
+        /// <summary>
+        /// Set the value of a field given its position in the schema.
+        /// This method is not meant to be called by user code, but only by
+        /// <see cref="SpecificDatumWriter{T}"/> implementations.
+        /// </summary>
+        /// <param name="fieldPos">Position of the field.</param>
+        /// <param name="fieldValue">Value of the field.</param>
         void Put(int fieldPos, object fieldValue);
     }
 }
diff --git a/lang/csharp/src/apache/main/Specific/SpecificWriter.cs b/lang/csharp/src/apache/main/Specific/SpecificWriter.cs
index ad58668..50fe46e 100644
--- a/lang/csharp/src/apache/main/Specific/SpecificWriter.cs
+++ b/lang/csharp/src/apache/main/Specific/SpecificWriter.cs
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -30,7 +30,17 @@ namespace Avro.Specific
     /// <typeparam name="T">type name of specific object</typeparam>
     public class SpecificWriter<T> : GenericWriter<T>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SpecificWriter{T}"/> class.
+        /// </summary>
+        /// <param name="schema">Schema to use when writing.</param>
         public SpecificWriter(Schema schema) : base(new SpecificDefaultWriter(schema)) { }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SpecificWriter{T}"/> class using the
+        /// provided <see cref="SpecificDefaultWriter"/>.
+        /// </summary>
+        /// <param name="writer">Default writer to use.</param>
         public SpecificWriter(SpecificDefaultWriter writer) : base(writer) { }
     }
 
@@ -172,6 +182,7 @@ namespace Avro.Specific
             throw new AvroException("Cannot find a match for " + value.GetType() + " in " + us);
         }
 
+        /// <inheritdoc/>
         protected override bool Matches(Schema sc, object obj)
         {
             if (obj == null && sc.Tag != Avro.Schema.Type.Null) return false;
diff --git a/lang/csharp/src/apache/test/Schema/SchemaNormalizationTests.cs b/lang/csharp/src/apache/test/Schema/SchemaNormalizationTests.cs
index 28ba7c8..71c249a 100644
--- a/lang/csharp/src/apache/test/Schema/SchemaNormalizationTests.cs
+++ b/lang/csharp/src/apache/test/Schema/SchemaNormalizationTests.cs
@@ -18,18 +18,17 @@
 
 using System;
 using System.Collections.Generic;
-using System.Linq;
 using System.Text;
 using NUnit.Framework;
 using System.IO;
 using Avro.Test.Utils;
-using Avro;
 
 namespace Avro.Test
 {
     [TestFixture]
     public class SchemaNormalizationTests
     {
+        private const long Empty64 = -4513414715797952619;
         private static readonly long One = -9223372036854775808;
         private static readonly byte[] Postfix = { 0, 0, 0, 0, 0, 0, 0, 0 };
 
@@ -70,8 +69,8 @@ namespace Avro.Test
 
         private static long AltFingerprint(string s)
         {
-            long tmp = AltExtended(SchemaNormalization.Empty64, 64, One, Encoding.UTF8.GetBytes(s));
-            return AltExtended(SchemaNormalization.Empty64, 64, tmp, Postfix);
+            long tmp = AltExtended(Empty64, 64, One, Encoding.UTF8.GetBytes(s));
+            return AltExtended(Empty64, 64, tmp, Postfix);
         }
 
         private static long AltExtended(long poly, int degree, long fp, byte[] b)